Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Python

This guide explains how to install the Python recorder wheel, capture a trace with your own interpreter, and open the resulting recording in CodeTracer.

1. Install codetracer_python_recorder

  1. Activate the environment that you normally use to run your Python code (virtualenv, uv, Conda, system Python, etc.). ct record always reuses whichever interpreter is active in your shell.

  2. Install (or upgrade) the recorder package:

    python -m pip install --upgrade codetracer_python_recorder

    If you use a tool like uv or pipx, run the equivalent command inside that tool so the recorder ends up on the same sys.path as your application.

  3. Optional: confirm the module is reachable by asking the interpreter for help.

    python -m codetracer_python_recorder --help

caution

If ct record cannot import codetracer_python_recorder, recording will fail with a module import error. Install the package in the interpreter you intend to trace or point Codetracer at a specific interpreter via CODETRACER_PYTHON_INTERPRETER=/path/to/python.

2. Record a trace

  1. From the same shell where the interpreter (and recorder wheel) are available, run:

    ct record path/to/script.py [-- <script arguments>]
    • Omit --lang; Python scripts are auto-detected.
    • Any arguments after -- are passed directly to your script.
    • Use CODETRACER_PYTHON_INTERPRETER if you need to force a specific interpreter (for example, inside CI).

  2. The command prints the trace identifier and the output directory (defaults to ., configurable with -o). The directory contains trace.json, trace_paths.json, and trace_metadata.json generated by the Python recorder via the db backend.

3. Open the trace

You can explore the recording immediately in the UI or later on:

  • Launch the GUI with the most recent trace:

    ct replay

  • Replay a specific Python trace by path:

    ct replay --trace-folder path/to/trace-output

  • Or jump straight from recording to replay in one command:

    ct run path/to/script.py [-- <script arguments>]

All three commands reuse the recorded artefacts created by codetracer_python_recorder, so you see the exact execution captured during ct record.