`compileall`

The Python compileall module provides utilities for byte-compiling Python source files (.py) into bytecode files (.pyc), making compiled bytecode available to users who lack write permissions to library directories and reducing startup overhead by skipping on-demand compilation. It works on an entire directory tree, a single file, or all locations on sys.path, and can be invoked from the command line or called programmatically:

>>> import compileall
>>> compileall.compile_dir(".", quiet=1)
True

Key Features

Recursively byte-compiles all .py files in a directory tree with compile_dir()
Compiles a single source file with compile_file()
Compiles all files found along sys.path with compile_path()
Supports parallel compilation using multiple worker processes
Allows control over recursion depth, optimization level, and bytecode invalidation mode
Can exclude files and directories by matching a regular expression pattern
Runnable as a command-line tool with python -m compileall

Frequently Used Classes and Functions

Object	Type	Description
`compileall.compile_dir()`	Function	Recursively compiles all `.py` files in a directory tree
`compileall.compile_file()`	Function	Compiles a single Python source file to bytecode
`compileall.compile_path()`	Function	Compiles all `.py` files found along `sys.path`

Examples

Compiling a single file and suppressing all output:

>>> import compileall
>>> compileall.compile_file("utils.py", quiet=2)
True

Excluding version-control directories during a directory tree compilation:

>>> import re, compileall
>>> compileall.compile_dir(
...     "src/",
...     rx=re.compile(r"[/\\][.]svn"),
...     quiet=1,
... )
True

Using the command line to compile a project directory with four parallel workers:

$ python -m compileall -j 4 project/

Common Use Cases

The most common tasks for compileall include:

Pre-compiling installed libraries to reduce import startup time
Preparing bytecode before deploying to read-only container environments
Verifying that all source files in a project parse without syntax errors
Generating optimized bytecode at multiple optimization levels for distribution
Integrating bytecode compilation into build and packaging pipelines

Real-World Example

When packaging a Python application for a Docker container with a read-only filesystem, pre-compiling bytecode prevents Python from attempting to write .pyc files at runtime. A build script can compile the entire application directory and exit with a non-zero status if any file fails:

import compileall
import sys

if __name__ == "__main__":
    success = compileall.compile_dir(
        "app/",
        maxlevels=10,
        force=True,
        quiet=1,
        workers=0,
    )

    if not success:
        print("Compilation failed. Check source files for syntax errors.")
        sys.exit(1)

    print("All source files compiled successfully.")

Run it during the Docker build:

$ python precompile.py
All source files compiled successfully.

The workers=0 argument tells compileall to use all available CPU cores, which speeds up compilation for large codebases.

Tutorial

How to Run Your Python Scripts and Code

Learn how to run Python scripts from the command line, REPL, IDEs, and file managers on Windows, Linux, and macOS. Master all execution approaches.

basics best-practices devops python

For additional information on related topics, take a look at the following resources:

Python Zip Imports: Distribute Modules and Packages Quickly (Tutorial)
How to Run a Python Script (Course)
How to Run Your Python Scripts (Quiz)

By Leodanis Pozo Ramos • Updated March 24, 2026

Python Standard Library Share Feedback

compileall