Serc

An experimental CPython bytecode compiler, written in Rust.

Highlights

• Compile Python source to CPython .pyc files without a CPython installation.
• Target Python 3.12, 3.13, 3.14, and 3.15 with a single executable.
• Check source files and recursively compile packages from the command line.
• Embed the compiler via the Rust library.

In a single-worker benchmark, Serc compiled NumPy faster than CPython’s built-in bytecode compiler. Serc also produces byte-for-byte identical output on an extensive corpus of real-world Python code, including Django, Airflow, and Transformers.

However, Serc is also experimental, and so may emit incorrect bytecode in some cases!

Installation

Install from crates.io with Rust 1.96 or later:

cargo install serc-cli --locked

Getting started

Given hello.py:

def greet(name):
    return f"Hello, {name}!"

Compile it to bytecode, emitted at __pycache__/hello.cpython-314.pyc:

serc compile hello.py

Pass a directory to compile its Python files recursively, or use --check to compile without writing cache files:

serc compile path/to/package
serc compile --check path/to/package

Compilation uses the available CPUs by default. Use --jobs (or -j) to set a limit, including --jobs 1 for serial compilation. You can also set the default with RAYON_NUM_THREADS:

serc compile --jobs 4 path/to/package

Python version

Serc emits Python 3.14-compatible bytecode by default, but supports target selection with --python-version. For example, to emit Python 3.15 bytecode:

serc compile --python-version 3.15 path/to/package

Serc supports the following CPython minor versions:

Each target writes its own cache tag and bytecode magic number, so the four versions can coexist under __pycache__.

Optimization

Use -O to remove assertions and set __debug__ to false, matching Python's -O mode. Use -OO to additionally remove module, class, and function docstrings:

serc compile -O hello.py
serc compile -OO hello.py

You can also select the level explicitly with --optimize 0, --optimize 1, or --optimize 2. Level 0 is the default. Optimized caches use Python's naming convention, such as __pycache__/hello.cpython-314.opt-1.pyc and __pycache__/hello.cpython-314.opt-2.pyc, so all three levels can coexist.

Rust library

Add Serc to your Cargo.toml:

[dependencies]
serc = "0.1.0"

Compile Python source and serialize the resulting code object in CPython's marshal format:

let module = serc::compile("print('Hello, world!')\n", "hello.py").unwrap();
let marshaled = module.marshal();

Compilation defaults to Python 3.14. See the library guide for selecting another Python version and generating .pyc files.

License

Serc is licensed under either of

• Apache License, Version 2.0, (LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or https://opensource.org/licenses/MIT)

at your option.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in Serc by you, as defined in the Apache-2.0 license, shall be dually licensed as above, without any additional terms or conditions.