vspdb 0.1.0

Run a Python script under the VS Code debugger from the terminal, halting on the first line.

vspdb — VS Code pdb for the terminal

Debug any Python script (with arguments) in the VS Code debugger straight from the terminal — no hand-written launch.json, no debug.py wrapper.

python -m vspdb my_script.py arg1 arg2

vspdb starts a debugpy debug server, gets VS Code to attach, and halts on the first line of your script — just like stopOnEntry. It ships a small VS Code helper (installed automatically) so this works with zero clicks.

---

Install — one package, that's it

pip install vspdb            # (or: pip install -e .  from this folder)

That's the only thing you install. vspdb ships a tiny VS Code helper extension inside the package and installs it into VS Code for you on first use. So:

python -m vspdb my_script.py 10      # explicit  (or: vspdb my_script.py 10)

The first run prints a one-time note that it installed the helper — reload the VS Code window once (Ctrl+Shift+P → "Developer: Reload Window"). After that it's fully automatic.

Tip: install into the same interpreter VS Code uses for the workspace (Ctrl+Shift+P → "Python: Select Interpreter") so breakpoints line up. You can also pre-install the helper without running a script: python -m vspdb --setup.

---

How you use it: zero clicks

Once the helper is active (after that one reload), just run scripts — each one attaches and halts on its first line, no debug panel, no F5:

python -m vspdb my_script.py 10
python -m vspdb another.py --flag

The helper keeps a debugpy listener ready in VS Code (one per window, on a per-project port) and vspdb connects to the right window automatically.

Don't want the helper? (no-extension fallback)

Run with --no-ext (or set VSPDB_NO_AUTO_EXTENSION=1). Then vspdb won't touch VS Code; instead it writes two configs to .vscode/launch.json and you attach manually:

• vspdb: Listen — start it once per window (F5), then runs are zero-click.
• vspdb: Attach — vspdb waits; press F5 once per run.

---

Options

python -m vspdb [options] <script.py> [script args...]

Everything after the script name is passed to your script untouched (so your script can use --port, --host, etc. without clashing with vspdb).

Option	Description
--port, -p PORT	Debug port (default: 5678).
--host HOST	Debug host/interface (default: 127.0.0.1).
--listen	Force listen mode (open the port, wait for VS Code).
--connect	Force connect mode (attach to a VS Code that is already listening).
--no-wait	Don't wait for VS Code; run immediately (disables stop-on-entry).
--no-stop	Attach, but don't halt on the first line.
--no-launch-json	Don't create/update .vscode/launch.json.
--setup	(Re)install the bundled VS Code helper extension and exit.
--no-ext	Don't auto-install the VS Code helper on this run.

The --port default is read from .vscode/vspdb.json (written by the helper) if present, else 5678. Disable auto-install globally with VSPDB_NO_AUTO_EXTENSION=1.

Examples:

# Different port
python -m vspdb --port 5690 my_script.py 10

# Your script gets its own --port; vspdb does not consume it
python -m vspdb server.py --port 8080 --debug

# Run under the debugger but don't stop on entry (rely on your own breakpoints)
python -m vspdb --no-stop my_script.py 10

---

How it works

1. Parses vspdb options, then treats the first positional as the script and the rest as the script's argv.
2. Installs the bundled VS Code helper into VS Code if it isn't there yet (unless --no-ext), and ensures .vscode/launch.json has the manual-fallback attach configs (merging, never clobbering, any existing file).
3. Resolves the port: if --port isn't given, it walks up from the script's directory for .vscode/vspdb.json (written by the auto-listen extension) so it attaches to the window that owns the script's project — important when several VS Code windows are open. Then it connects if that port is being listened on, otherwise listens and waits for VS Code.
4. Once the client is attached, it runs your script as __main__ with the right sys.argv, having injected a debugpy.breakpoint() at the first executable line so the debugger halts there. Original line numbers are preserved, so tracebacks stay accurate.

---

Requirements

• Python 3.8+
• debugpy (installed automatically)
• VS Code with the Python / Python Debugger extension

Author

Kaustubh — [e-mail] · github.com/kmhatre14

License

MIT. Built with assistance from Claude Opus 4.8.