Seam for VS Code
Debug Python and C, C++ or Rust in one session.
Step Into a native function called by Python, inspect its variables, and Step Out
to Python. Set breakpoints in either language. The call stack shows Python and
native frames in the order they ran.
Seam supports C API, PyO3, pybind11, nanobind and Cython extension modules.

Recorded with the packaged extension. Python calls Rust's sum_squares and
receives 30. The recording starts at a Python breakpoint.
Install
On Windows, open your project in WSL and install Seam on the WSL side.
On Ubuntu 24.04, install LLDB in a Linux or WSL terminal:
sudo apt-get update
sudo apt-get install -y lldb-19
On macOS, install Apple's command-line tools:
xcode-select --install
Install Seam from the Marketplace,
then open the Command Palette and run Seam: Check This Machine.
It checks dependencies and the project interpreter, runs a debug session,
and reports what to fix.
The extension includes the debugger and compiled helper. You do not need to
install Seam with pip or compile it. Linux x64 and macOS ARM64 VSIX files are also available from
GitHub Releases.
Choose the file for your platform and run Extensions: Install from VSIX....
Requirements
- Apple Silicon macOS 14 or newer, or Linux x86-64 with glibc. Windows uses WSL.
- LLDB with Python scripting support. Use Apple's command-line tools on macOS.
On Linux, versions 18, 19 and 20 are tested.
Use 19 or 20 for new installations. Seam chooses
lldb-20, then lldb-19,
then lldb. Set SEAM_LLDB to override that choice. The machine check warns
about LLDB 18's threaded-child-process session failure.
- CPython 3.12, 3.13 or 3.14 for your program. Python 3.15.0rc3 also passes the
Linux compatibility tests; later 3.15 builds have not been validated. Use a native
ARM64 interpreter on macOS. The system Python and Rosetta targets are unsupported.
- Build your native extension with debug information for source stepping. Use
-g for C and C++, a Rust debug build, or [profile.release] debug = true
for Rust release builds. Building your extension still needs its toolchain.
Seam runs its adapter with the program's interpreter when possible, then tries
other Python installations on the machine. It needs Python 3.12 or newer to run
the adapter. If Python or LLDB is missing, VS Code reports why it cannot start.
Start debugging
- Open your project and a Python file.
- Set a breakpoint on a line that calls your native extension.
- Press F5. If VS Code asks, choose Seam: Python + native.
- Use Step Into to enter the native function. Step Out returns to Python.
You do not need a launch.json. To save a configuration:
{
"type": "seam",
"request": "launch",
"name": "Seam: current file",
"program": "${file}"
}
For a runnable example, use the
Python and Rust demo.
Choose an interpreter
Seam uses the interpreter selected in Microsoft's Python extension. Without that
selection, it checks python.defaultInterpreterPath, then .venv and venv in
the workspace, then python3. Set "python" in the launch configuration to choose
one explicitly. The Seam output channel records the choice.
Attach to a running program
{
"type": "seam",
"request": "attach",
"name": "Seam: attach",
"pid": "${command:seam.pickProcess}"
}
The picker lists your Python processes with their process IDs, interpreters and
working directories, newest first. You can also set "pid" to a number. Attach needs
debugging permission. On Linux, a non-child process needs ptrace_scope set to 0
or explicit tracing permission. On macOS, the target must allow debugging; protected
system processes cannot be attached. The main thread must be able to load Seam's helper.
Inspect the program

- Set breakpoints in
.py, .c, .cpp, .rs and .pyx files as usual. Conditions, hit
counts and log messages work on both sides.
- The Breakpoints view offers five exception stops: uncaught Python exceptions (on by
default), raised Python exceptions, user-unhandled Python exceptions, C++ throw and Rust panic.
- The program runs in the integrated terminal, so it can read input. Set
"console": "internalConsole" to send its output to the Debug Console instead.
- A crash in native code (segfault, abort) stops at the faulting line, with the Python
frames that led there.
At a native stop, select a Python caller to inspect its locals and globals without
running Python in the paused process:

When a native frame has no source, select it in Call Stack and choose
Open Disassembly View. With that view focused, Step Into and Step Over
advance one instruction at a time.

The main README lists every launch option.
Limitations
- Native Windows, Intel Macs, Rosetta targets, Linux ARM, Alpine/musl,
free-threaded Python, PyPy and the experimental JIT are outside the validated scope.
- At native stops, Python values are read from memory. Simple built-in types show
values; other objects show their type and address. Python evaluation, object
expansion and mutation require a safe Python stop.
- Optimised native code can lose source lines, locals or frames. A debug build gives
the most reliable source stepping.
- Child processes run but are not debugged. Use LLDB 19 or 20 to avoid LLDB 18's
threaded-child-process session failure.
- An evaluated expression that crashes or times out can damage the program.
Restart the session before evaluating again.
- Attach needs debugging permission and a responsive interpreter; blocked-process
attach and remote debugging are outside the supported scope.
- Disassembly breakpoints are not supported. Linux thread-heavy workloads measured about
twice as slowly; there is no universal low-overhead guarantee.
- On macOS, Step Into from Python excludes native modules with more than 20,000
functions. A 15,000-function check took about three seconds for repeated Step Into.
Set a source or function breakpoint to enter larger modules. LLDB can omit the
interrupted native frame when a signal handler runs; Python callers remain visible.
See the complete limitations.
Settings
| Setting |
Meaning |
seam.adapterCommand |
Leave empty to use the included debugger. To use another installation, set a command such as ["/path/to/venv/bin/seam", "dap"]. |
seam.logFile |
Set a file path to record protocol messages for troubleshooting. |
Troubleshooting
Run Seam: Check This Machine first. For a grey native breakpoint, check debug
information and compiler optimisation. If source paths changed after the build,
the Debug Console suggests a sourceMap entry when possible.
For a bug report, include the machine-check
output, what failed, and how to reproduce it. Set seam.logFile, reproduce the
problem, and include that log, its .lldb companion and the Seam output channel.
Check logs for private paths and values before sharing them.
Building from source
Run scripts/build-vsix.sh from the repository. It builds the VSIX for the host platform.
Passing a wheel path uses the adapter and helper from that wheel. See the
contributor guide.