uv --compile-bytecode: Faster Cold Starts in CI
uv --compile-bytecode pre-compiles installed Python modules into .pyc files so the first import at runtime is faster.
By default uv skips bytecode compilation, leaving it to the first run. In images and short-lived containers, compiling at install time trades a slower install for faster cold starts.
What it does
uv --compile-bytecode (or UV_COMPILE_BYTECODE=1) compiles the installed .py files to .pyc during install, the way pip does by default. This adds time to uv sync or install but means the interpreter does not pay the compile cost on first import.
Common usage
uv sync --compile-bytecode
uv pip install --compile-bytecode -r requirements.txt
UV_COMPILE_BYTECODE=1 uv sync --frozen
# typical Dockerfile line
# ENV UV_COMPILE_BYTECODE=1Options
| Flag / Env | What it does |
|---|---|
| --compile-bytecode | Compile modules to .pyc during install |
| UV_COMPILE_BYTECODE | Env var to enable it (1) globally |
| --no-compile-bytecode | Force-disable compilation |
In CI
Enable UV_COMPILE_BYTECODE=1 when building container images or any artifact whose Python processes are short-lived, so the cold-start import cost is paid once at build time. Skip it for a throwaway test environment where the install time matters more than first-import speed.
Common errors in CI
Compilation surfaces syntax problems early: "SyntaxError" during install means a module that pip would have failed on lazily; the package is broken on this Python version. The main visible effect is a longer uv sync; if a build step times out after enabling it, raise the timeout or compile only the final image layer.