Jit

CPython JIT Compiler Development

The JIT uses copy-and-patch compilation: at build time, each micro-op (uop) is compiled to a native code "stencil" with holes for runtime values. At runtime, _PyJIT_Compile() copies stencils and patches in actual addresses/operands.

Architecture reference: InternalDocs/jit.md

Prerequisites

Load the build skill first if you haven't configured and built CPython yet.

Building the JIT requires the specific LLVM major version pinned in Tools/jit/_llvm.py (_LLVM_VERSION) — check that file first; the pin advances over time and older branches pin older versions. Only clang and llvm-readobj are needed; llvm-objdump is recommended. With <V> as the pinned version, check availability:

grep _LLVM_VERSION Tools/jit/_llvm.py
clang-<V> --version 2>/dev/null || clang --version 2>/dev/null

If not installed:

• Ubuntu/Debian: wget https://apt.llvm.org/llvm.sh && chmod +x llvm.sh && sudo ./llvm.sh <V>
• Fedora 40+: sudo dnf install 'clang(major) = <V>' 'llvm(major) = <V>'
• macOS (Homebrew): brew install llvm@<V>
• Dev Containers / Codespaces: the required LLVM is pre-installed
• Windows: Downloaded automatically by PCbuild\build.bat

Building with JIT

# Full JIT (native code compilation)
cd $BUILD_DIR && CC="ccache gcc" ../configure --enable-experimental-jit --with-pydebug
make -j $NCPU

# Tier 2 interpreter only (no native compilation, useful for debugging uop logic)
cd $BUILD_DIR && CC="ccache gcc" ../configure --enable-experimental-jit=interpreter --with-pydebug
make -j $NCPU

Configure options for --enable-experimental-jit

Runtime toggle: set PYTHON_JIT=0 or PYTHON_JIT=1 to override the build default.

Key Files

Build-time stencil generation (Tools/jit/)

Runtime (Python/)

Headers

Generated at build time

Build Pipeline

Python/bytecodes.c
    |  (Tools/cases_generator/tier2_generator.py)
    v
Python/executor_cases.c.h
    |  (Tools/jit/build.py reads each "case OPNAME:" block)
    v
For each uop: template.c + case → {OPNAME}.c
    |  (clang --target={triple} -Os -S)
    v
{OPNAME}.s
    |  (_optimizers.py: branch inversion, dead code removal)
    v
{OPNAME}.s (optimized)
    |  (clang -c)
    v
{OPNAME}.o
    |  (llvm-readobj → JSON → _stencils.py parses relocations)
    v
StencilGroup (code bytes + holes)
    |  (_writer.py)
    v
jit_stencils.h (emit_* functions + StencilGroup table)

Regenerating JIT Stencils

You must regenerate stencils after:

• Editing Python/bytecodes.c (uop definitions)
• Modifying any file in Tools/jit/
• Changing pyconfig.h (configure options)

# Regenerate stencils
make -C $BUILD_DIR regen-jit

# Force full rebuild (ignores digest cache)
python3 Tools/jit/build.py --force -d -o $BUILD_DIR -p $BUILD_DIR <target-triple>

# Clean stencils (forces regeneration on next build)
make -C $BUILD_DIR clean-jit-stencils

# Then rebuild
make -C $BUILD_DIR -j $NCPU

The stencil build uses a SHA-256 digest of all inputs. If the digest hasn't changed, make skips regeneration. Use --force or clean-jit-stencils to override.

Testing

The optimizer and executor infrastructure is tested in Lib/test/test_optimizer.py. Otherwise, the JIT is tested by running the standard test suite with JIT enabled:

# Standard test run (JIT is active if configured with --enable-experimental-jit)
$BUILT_PY -m test -j $NCPU

# Run specific tests
$BUILT_PY -m test test_capi test_sys -j $NCPU

# Disable uop optimization (test stencils with unoptimized traces)
PYTHON_UOPS_OPTIMIZE=0 $BUILT_PY -m test -j $NCPU

# Disable JIT at runtime (fall back to Tier 2 interpreter)
PYTHON_JIT=0 $BUILT_PY -m test -j $NCPU

# Enable JIT at runtime (for yes-off builds)
PYTHON_JIT=1 $BUILT_PY -m test -j $NCPU

Debugging JIT Issues

Common problems

• Segfault in JIT code: Usually a patching bug or stale stencils. Run make clean-jit-stencils && make -j $NCPU and retest.
• "Can't find clang-NN!": The pinned LLVM version isn't installed or on PATH. See Prerequisites.
• Stencil digest mismatch: After editing bytecodes, run make regen-jit before rebuilding.
• Wrong results with JIT: Compare PYTHON_JIT=1 vs PYTHON_JIT=0 to isolate. If only JIT fails, the bug is in stencil generation or patching.

Inspecting generated stencils

# View the generated stencils header (contains disassembly in comments)
less $BUILD_DIR/jit_stencils.h

# Build with verbose output to see clang invocations
python3 Tools/jit/build.py -v -d -o $BUILD_DIR -p $BUILD_DIR x86_64-unknown-linux-gnu

Debugging at the C level

Build with --with-pydebug for assertions in Python/jit.c. Key functions to set breakpoints on:

• _PyJIT_Compile - trace compilation entry point
• _PyJIT_Free - executor cleanup
• _PyOptimizer_Optimize - trace construction (in Python/optimizer.c)

Environment variables for debugging

Supported Platforms

Key Concepts

• Stencil: Pre-compiled native code for one uop, with "holes" for runtime values (operands, jump targets, symbol addresses).
• Hole: A relocation record (offset + type + patch function) filled at JIT compile time.
• preserve_none calling convention: Used for tail calls between JIT stencils. Only Clang supports this (__attribute__((preserve_none))), which is why LLVM/Clang is required.
• musttail: Guaranteed tail call elimination, essential for the continuation-passing style between stencils.
• GOT (Global Offset Table): Per-stencil table for resolving external symbols at runtime.
• Executor: _PyExecutorObject - holds the uop trace and (if JIT-compiled) a jit_code function pointer.
• PY_MAX_JIT_CODE_SIZE: Maximum JIT-compiled trace size (see Include/internal/pycore_jit.h for the current value). Traces exceeding this fall back to the Tier 2 interpreter.