Debugging Xpra
August 8, 2026 · View on GitHub
Practical steps for collecting diagnostics, isolating problems, and investigating crashes.
Start here
The built-in bug reporting tool is available from most dialog screens and the system tray menu. It collects much of the information needed when filing a bug report. The Session Info dialog is also useful for diagnostics.
Before reporting a problem:
- Disable optional features such as clipboard, audio, and OpenGL to narrow down the cause.
- Try different picture encodings.
- If possible, try another operating system, client—such as the built-in HTML5 client—or Xpra version.
- Capture the output of
xpra info.
The xpra toolbox, also available from the main launch screen, can run either
natively on the client or through an Xpra session on the server. Comparing the
test results from both sides can reveal where a problem originates.
Tip
Debug logging is the most common diagnostic technique. Enable the categories related to the affected subsystem.
Topic-specific guides
Debugging crashes with GDB
When an Xpra process crashes with “core dumped,” use GDB to obtain a backtrace.
Attach to a running process
Find the Xpra process ID:
ps -ef | grep xpra
Attach GDB to it:
gdb python $PID_OF_XPRA_PROCESS_TO_DEBUG
After the debug symbols have loaded, resume the process:
(gdb) continue
Start Xpra in GDB
gdb /usr/bin/python3
run /usr/bin/xpra start ...
Alternatively:
gdb --args /usr/bin/python /usr/bin/xpra start ...
run
Capture the backtrace
When the crash returns control to GDB, capture both the Python stack trace with
py-bt and the full stack trace with bt.
Debug symbol packages must be installed separately. Consult your distribution's instructions, such as Debian's backtrace guide or your package manager's debuginfo support.
Signal handling
Xpra handles SIGINT, SIGTERM, SIGUSR1, and SIGUSR2. To prevent GDB from
intercepting SIGINT, use handle SIGINT nostop pass:
gdb -ex "handle SIGINT nostop pass" \
--args /usr/bin/python3 /usr/bin/xpra start :20 --no-daemon --start=xterm