debug.md

Debug Command

pipxu adds a debug command which pipx does not have.

usage: pipxu debug [-h] [-e EXECUTABLE] [-d DEBUGGER] package [args ...]

The debug command is useful for developers who want to easily run an installed Python application using a debugger, usually when they have installed that application in editable form, e.g.

$ cd myproject
$ pipxu install -e .

The command tries to work out your preferred debugger package from the standard PYTHONBREAKPOINT environment variable. If that variable is not set it defaults to the standard pdb. Or you can set the debugger package explicitly with the -d/--debugger option.

E.g. my personal preference is to use pudb debugger so I have PYTHONBREAKPOINT=pudb.set_trace set in my environment for normal Python breakpoint() debugging. So to debug myproject from that same directory and from start I would use:

pipxu debug . <myproject-args>

And the above would start the myproject application (with passed <myproject-args>) in the pudb debugger within my terminal. To be more explicit, this is equivalent to:

pipxu debug -d pudb . <myproject-args>

The command assumes the executable name is the same name as the package which is usually the case. But if it is not then you can specify the executable using the -e/--executable option.

pipxu debug -e <myproject-exe-name> . <myproject-args>

If you want to specify - or -- options to your command being debugged then you must delimit them from arguments to pipxu with --, e.g.

pipxu debug -d pudb . -- <-m --myarg-long-opt>

Of course the python installed in the virtual environment is used to run the application so that virtual environment must have the debugger package installed. So it is very common to get an error message, e.g. No module named pudb when you first try to use the pipxu debug command for your project. In that case you simply install the debugger package, e.g.pudb, to that virtual environment, i.e:

pipxu inject . pudb

Then run your pipxu debug command again.