Remote Debugger

In PyDev you can debug a remote program (a file that is not launched from within Eclipse).

The steps to debug an external program are:

• 1. Start the remote debugger server
• 2. Go to the debug perspective
• 3. Start the external program with the file pydevd.py in its PYTHONPATH
• 4. Call pydevd.settrace()
• Note: if the program is being edited inside of PyDev (and launched externally), you can write only pydevd and request a code-completion which will add pydevd.py to sys.path and do the settrace (i.e.: steps 3 and 4).
• 5. Adjust Path Mappings

Let's see a simple step-by-step example on how this works:

1. Start the remote debugger server: To start the remote debugger server, go to the menu: PyDev > Start Debug Server. When running, a Debug Server entry should appear in the Debug Stack view.

Note: That menu item should be present at the debug perspective and it can be enabled in other perspectives through Window > Perspective > Customize perspective > Tool Bar Visibility > PyDev debug.

Image: Remote Debugger Server

2. Go to the debug perspective: This is needed because it has no actual 'signal' that it reached a breakpoint when doing remote debugging. So, if you already have it open, just cycle to it with Ctrl+F8. Otherwise, go to the menu: window > Open Perspective > Other > Debug.

3. Call pydevd.settrace(). If the program is being edited inside of PyDev (and launched externally), you can write only pydevd and request a code-completion which will add pydevd.py to sys.path and do the pydevd.settrace().

Note if you're launching from a different computer, you have to get the PyDev.Debugger in the target computer. If you're in the latest version, it may be installed with pip install pydevd. That usually works as pydevd is usually backward compatible, but if for some reason it doesn't work because your PyDev version is too old, you may have to check the version of pysrc/pydevd.py in the contents of org.python.pydev.core plugin from your Eclipse installation to install the proper version of the debugger (or just copy the full contents of that directory to the target machine and add it to the PYTHOHNPATH).

4. Launch the program and wait for it to reach the pydevd.settrace() call: When that call is reached, it will automatically suspend the execution and show the debugger.

Image: pydevd.settrace called

5. Path Mappings

You can have the running program in one machine and PyDev on another machine, but if the paths are not exactly the same the Path Mappings must be set in the Preferences, in PyDev > Debug > Path Mappings

Hint: it's possible to click the Add path mapping template entry button to pre-fill with a template and it may be useful to check the Debug path translation while you're trying to ge the path mappings correct.

Keep in mind that the localRoot is the path from the machine where Eclipse/PyDev is running, whereas the remoteRoot is the one where the python process is running.

Image: path mapping configuration

Important Notes

NOTE 1: the settrace() function can have an optional parameter to specify the host where the remote debugger is listening. E.g.: pydevd.settrace(host='10.0.0.1')

NOTE 2: the settrace() function can have optional parameters to specify that all the messages printed to stdout or stderr should be passed to the server to show. E.g.: pydevd.settrace(stdout_to_server=True, stderr_to_server=True)

See below for the arguments that may be customizable in `settrace`:

  
:param host: host to connect to, if the client is not in the same machine (default is the localhost)

:param stdout_to_server: when this is true, the stdout is passed to the debug server

:param stderr_to_server: when this is true, the stderr is passed to the debug server
    so that they are printed in its console and not in this process console.

:param port: specifies which port to use for communicating with the server (note that the server must be started
    in the same port). @note: by default it's 5678 in PyDev, but it may be customized in the debug preferences.

:param suspend: whether a breakpoint should be emulated as soon as this function is called.

:param trace_only_current_thread: determines if only the current thread will be traced or all current and future
    threads will also have the tracing enabled.