Skip to content

UV Script Runner & Debugger

Run and debug [project.scripts] and [project.gui-scripts] entry points in uv projects directly from pyproject.toml or the Run menu. BetterPy keeps matching Python run configurations in sync so scripts stay available in the Run dropdown.

Overview

When working with uv Python projects, entry points are declared in pyproject.toml:

[project.scripts]
mytool = "mypackage.cli:main"

[project.gui-scripts]
myapp = "mypackage.gui:start"

BetterPy automatically parses entry points and provides:

  • Gutter Run Icons: Click green play icons next to valid entry point declarations in pyproject.toml. Empty or unresolved targets do not get an icon.
  • Run Configurations: Detected scripts get a workspace-local uv: <script> configuration. Existing or customized configs for the same script are reused and never overwritten. Plugin-owned configs are removed when a script is commented out or deleted.
  • Run & Debug Actions: Execute scripts directly with the Python debugger (pydevd) attached.
  • Context Menu Actions: Right-click entry points in pyproject.toml to run or debug.
  • Search & Quick Picker: UV: Debug / Run Project Script... search menu with argument prompts.
  • Last Run Re-execution: UV: Debug / Re-run Last Script to instantly re-run your previous script.
  • Generate Entry Point: When pyproject.toml has no [project.scripts] mapping, use Generate → uv: script entry point to insert it with a live-template key and an empty target string.

Quick Start

  1. Open a pyproject.toml file.
  2. If it has no [project.scripts] mapping, choose Generate → uv: script entry point. Otherwise, skip to step 4.
  3. Fill in the script name and target in the live template.
  4. Click the green play icon in the gutter next to the entry point name.
  5. Select Run or Debug.