compileall

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
• Rewrites the paths recorded in .pyc files with stripdir and prependdir, and deduplicates identical bytecode across optimization levels with hardlink_dupes
• 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

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.

Related Resources

Tutorial

What Is the __pycache__ Folder in Python?

In this tutorial, you'll explore Python's __pycache__ folder. You'll learn about when and why the interpreter creates these folders, and you'll customize their default behavior. Finally, you'll take a look under the hood of the cached .pyc files.

intermediate python

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

• How to Run Your Python Scripts and Code (Tutorial)
• Python Zip Imports: Distribute Modules and Packages Quickly (Tutorial)
• What Is the __pycache__ Folder in Python? (Quiz)
• How to Run a Python Script (Course)
• How to Run Your Python Scripts (Quiz)