Package: debugpy-run
DEBUGPY-RUNThis utility facilitates debugging aPythoncommand line program usingPython
extensioninVisual Studio Code.ThePython
debuggerinVS
Codeis superb. However debugging a
command line program which takes arguments is a little awkward to
invoke. Theofficial
instructionsrequire you to edit the command line arguments in yourlaunch.jsonconfiguration which is cumbersome to do when you want to change
arguments for each run, particularly because thearguments have to be
quoted within a JSON data
structure.
Thisquestion on
stackoverflowdescribes the problem, but there is no adequate solution. This utility
provides a solution, follow theprocedure to use
itbelow.If you have theVS Code Python
extensioninstalled then the fulldebugpydebugger is already
bundled with it. You open a terminal window and run this utility to
invoke your program with arguments. The utility finds the path wheredebugpyis installed and then
runs it for the program and arguments you specify, in listen mode.
Connect to it from withinVS Codeusing the PythonRemote Attachdebug configuration (using the default
host and port settings). You cancontrol+cand then re-run the command
with changed arguments using your shell history and command line editing
facilities, for each debug run. You can also rundebugpy-runremotely,
withdebugpyexplicitly installed for this case, to debug fromVS
Codeto a remote machine over a
network.This utility was developed on Arch Linux but should work on all Linux
systems whereVS Codeis installed
with thePython
extension. The
latest version and documentation is available athttps://github.com/bulletmark/debugpy-run.InstallationArch users can installdebugpy-run from the
AUR.Python 3.6 or later is required. Also, the Pythonpackagingmodule is required.
Notedebugpy-run is on PyPIso
just ensure thatpipxis installed
then type the following:$ pipx install debugpy-runTo upgrade:$ pipx upgrade debugpy-runTo remove:$ pipx uninstall debugpy-runProcedure to UseOpenVS Codefor the directory
where your command line program is located.Ensure you have added aDebugging
Configurationin yourlaunch.json. SpecifyRemote Attachand just accept the
default arguments (i.e. host =localhost, port =5678). You only
have to do this once for each project.Open a terminal (either withinVS
Code, or external) and type:$ debugpy-run my-program -- --myargsNowdebugpy-runwill start thedebugpydebugger for your program,
output a message, and then wait to be connected byVS
Code.:warning: As seen in the above example, you should specify--after your program/module name so that debugpy-run knows where it's
own options end, and the target options start.:warning: You must runmy-programfrom same work directory as VS
Code is using otherwise VS Code will not correlate your source file
path with the code being run by debugpy. I.e. if the program is
located atsrc/my-programwith respect to the work directory then
you must run it asdebugpy-run src/my-program -- --myargsInVS Code, start debugging, e.g.
set a breakpoint then start theRemote Attachdebug session.At any point you cancontrol+cthe terminal command and restart it
with new command line arguments (e.g. using the convenience of your
shell history and editing commands) and then restart the debug
session inVS Code.Remote Debugging On Another HostThedebugpy-runutility first looks to find thedebugpypackage in
your local~/.vscode/extensionsdirectory. If it fails to find that
thendebugpy-runnext tries to importdebugpyglobally. This is is
done so you can install bothdebugpy-runanddebugpyon a remote
headless server (e.g. whereVS Codeis
not installed) and then debug a program on that server fromVS
Codeon your laptop/PC remotely over
the network.So for example, I may have a program which runs on a server which want
to debug fromVS Codeon my laptop. I
first make sure I install the necessary software on the server (you can
also do this in the programs virtual environment of course):$ pipx install debugpy
$ pipx install debugpy-runThe start my program on the server using the debugger:$ debugpy-run -p :5678 my-program -- --myargsNOTE: We need to explicitly specify the:portfor this case so that
the port is opened on the external network interface so we can connect
to it from another machine. By default,debugpy-run/debugpyotherwise only accept local connections.Then I go back to my laptop, ensure I have set upRemote Attachdebugging configured with host =my-serverand port =5678, then start
debugging.Of course, you could startdebugpydirectly yourself on the server but
thedebugpy-runwrapper is more convenient to use and makes the usage
consistent with the familiar way you startdebugpy-runon your
laptop/PC.Debugging A Program Running As RootAnother application ofdebugpy-runis that you can, as your normal
user, easily useVS Codeto debug a
program you run as root. E.g. run a program usingsudo:$ sudo debugpy-run my-program -- --myargsNow you can justRemote Attachto it inVS
Codeas your normal user.UsageTypedebugpy-run -hto view the usage summary:usage: debugpy-run [-h] [--listen] [-W] [-C] [-p PORT] [-g] [-r]
                      [--log-to PATH | --log-to-stderr]
                      [-m MODULE | -c CODE | --pid PID | -V]
                      [program] ...

Finds the "debugpy" package within your VSCode Python extension and then runs
it for "remote attach" debugging of the program/module you specify. If not
found in extensions then tries to run the globally installed "debugpy".

positional arguments:
  program               python program to execute and debug
  args                  remaining arguments to debug

options:
  -h, --help            show this help message and exit
  --listen              listen on given port, default=True
  -W, --no-wait         do not wait on listen for client, start immediately
  -C, --connect         connect to given port rather than listen
  -p PORT, --port PORT  [host:]port to use, default=5678
  -g, --global-only     only run the globally installed debugpy
  -r, --run-on-error    re-run program/module even on error
  --log-to PATH         log to given path
  --log-to-stderr       log to stderr
  -m MODULE, --module MODULE
                        python module to execute and debug
  -c CODE, --code CODE  python code to execute and debug
  --pid PID             python pid to attach and debug
  -V, --version         output debugpy path and versionLicenseCopyright (C) 2021 Mark Blakeney. This program is distributed under the
terms of the GNU General Public License.
This program is free software: you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by the
Free Software Foundation, either version 3 of the License, or any later
version.
This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
Public License athttp://www.gnu.org/licenses/for more details.