Starting Debug Automatically Using sitecustomize

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

It is possible to use Python's sitecustomize feature (provided by the site standard library module) to automatically start debugging all code that runs using a particular Python installation.

To set this up on the same host where Wing is running:

(1) Make a new directory sitecustomize and then add a file named to the directory with the following contents:

from . import wingdbstub

This is the hook that will cause Python on the containers to load Wing's debugger. It is loaded by Python's Site-specific configuration hook.

(2) Configure a copy of Wing's to place into this sitecustomize directory.

You can find the master copy of at the top level of your Wing installation (or on macOS in Contents/Resources inside If you don't know where this is, it is listed as the Install Directory in Wing's About box.

You will need to make copy of this file to your sitecustomize package directory.

On macOS or if you installed Wing from the .zip or .tar installer, you will need to set WINGHOME inside your copy of to the full path of your Wing installation -- the same place you found the file.

(3) Move your sitecustomize directory into the site-packages directory in your Python installation.

You can determine this value by starting Python and inspecting it with the following lines of code:

>>> import os, sys, site
>>> v = sys.version_info[:2]
>>> print(os.path.join(site.USER_BASE, 'lib', 'python{}.{}'.format(*v), 'site-packages'))

This prints the location where you need to move your sitecustomize directory.

(4) Configure Wing to listen for externally initiated debug connections. This is done by clicking on the bug icon bugicon in the lower left of Wing's window and enabling Accept Debug Connections.

If your debug process spawns child processes that you also wish to debug, then you will also need to open Project Properties from the Project menu and set Debug Child Processes under the Debug/Execute tab to Always Debug Child Processes.

Starting Debug

Wing should now debug any Python code run using your Python installation, not matter how it is started. Python loads your sitecustomize before any other code is run, which imports wingdbstub and thus starts debug and makes a connection to the IDE.

To temporarily disable debug without making any other changes, turn off Accept Debug Connections again as described in step (4) above.

Remote Hosts and Containers

This technique also works to automatically start debug on a remote host or container.

On a remote host, first follow the instructions in Debugging Externally Launched Remote Code to get remote debugging working. Then proceed with the instructions above, using the copy of from the remote agent installation on the remote host (usually ~/.wingpro8/remote-8.0.4). That file is already pre-configured to work on your remote host.

On a container, first follow the instructions for Working with Containers and Clusters and then set up your sitecustomize so it is mounted into site-packages on your container. You will need to edit your copy of to set WINGHOME to /wingpro8 and kHostPort to <hostname>:50005 where <hostname>> is replaced with the name of the host system as viewed from the container. For Docker, this is usually host.docker.internal:50005. Note that this assumes you are using the default debug port in Wing; if not, use the value set with the Debugger > Listening > Server Port preference.


If you can't get the debugger to connect, try setting kLogFile in your copy of to "<stderr>" or a valid log file name. You can email this output to for help.