Using wingdb to Initiate Debug

Index of All Documentation » Wing Pro Reference Manual » Advanced Debugging Topics »


Debug can be started on the command line by running wingdb (or wingdb.exe on Windows) from the top level of the Wing installation. These are invoked like the Python command line, after setting some environment variables that tell Wing which Python installation to use and how to connect to the IDE.

Minimal Configuration

First make sure that Wing is listening for debug connections by clicking on the bug icon in the lower left and enabling Accept Debug Connections.

Next set the environment variable WINGDB_PYTHON to the full path to the python or python.exe to use. This is needed only if you do not want to use the default python.

Now you can start debugging by running wingdb (or wingdb.exe) as if it were Python. Debugging should start and the process should connect back to Wing.

For example on Windows:

set WINGDB_PYTHON=C:\Python38\python.exe
"C:\Program Files (x86)\Wing Pro 10\wingdb.exe" myscript.py arg1 arg2

On Linux:

export WINGDB_PYTHON=python3.8
/usr/lib/wingpro10/wingdb myscript.py arg1 arg2

On macOS:

export WINGDB_PYTHON=python3.8
"/Applications/WingPro.app/Contents/Resources/wingdb" myscript.py arg1 arg2

Advanced Configuration Options

Other environment variables that control the debugger's behavior include:

WINGDB_PYARGS provides any arguments to send to Python itself. Do not use this for arguments sent to your Python code. Those are specified on the command line instead.

WINGDB_STEPINTO is set to 0 or 1 to indicate whether to stop on the first line of code (default=0)

WINGDB_WAIT_ON_EXIT controls whether the debug process should wait on exit for further interaction with the debugger (default=don't wait)

WINGDB_ENV_FILE causes the debugger to load environment from this file and then exec sys.executable in the environment, rather than running in the inherited environment. The environment file contains a sequence of byte strings, each separated by a '\0' byte. The 1st of every pair is a key and the 2nd is the value. (default=run in inherited environment)

WINGDB_HOSTPORT is the host:port where the IDE is running, if different than the default of localhost:50005. The host can be either a host name or an IP address and the port is the one shown when the mouse is hovered over the bug icon in the lower left of Wing's main window. We strongly recommend using Wing Pro's Remote Hosts feature instead. Otherwise, you'll also need most of the tedious manual configuration described in Manually Configured Remote Debugging.

WINGDB_SECURITYTOKEN can contain the security token to use for authentication with the IDE. If not specified, the default is to read the token from the wingdebugpw file in the user settings directory (the value used is the portion after the :).

WINGDB_USERSETTINGS is used only to find the debugger implementation if provided by an update made while running Wing with a non-default Settings Directory, as specified using the --settings command line argument (default=use the standard location for the directory)

WINGDB_LOGFILE is the full path to a diagnostic log file. Set this only at the request of Wingware Technical Support. It will slow down the debugger (default=no logging)

WINGDB_LOGVERYVERBOSE controls whether to print extremely verbose low-level diagnostic logging. Set this only at the request of Wingware Technical Support. It will drastically slow down debugging (default=off)

The following env is relevant only for Python 3.12 and later:

WINGDB_USELEGACYTRACERCORE can be set to 1 to force Wing to always use the legacy debugger core, rather than using the new optimized debugger core that is based on debugging features found only in Python 3.12+.

The following optional envs are only used to support Python 2.5; in Python 2.6+ set PYTHONIOENCODING instead:

WINGDB_STDOUT_ENCODING sets the encoding to use for stdout

WINGDB_STDIN_ENCODING sets the encoding to use for stdin