pycompile

pycompile [options] [path ...]

-O, --optimize
    Compile with optimization level 1. Generates .pyc files without docstrings.

-OO
    Compile with optimization level 2. Generates .pyc files without docstrings and assertions.

-V, --version
    Show program's version number and exit.

-f, --force
    Force recompilation of all files, even if timestamps are current.

-p, --package
    Specify the package name (used by Debian packaging tools).

-r, --remove
    Remove obsolete bytecode files (e.g., from old Python versions or uninstalled source).

-X, --exclude
    Exclude files or directories matching the given pattern.

-s, --single-version-externally-managed
    For specific Python package management setups (usually related to distutils or setuptools).

-v, --verbose
    Increase verbosity of output.

--
    Separator indicating the end of options; subsequent arguments are treated as paths.

path ...
    One or more paths to directories or specific Python source files to compile. If omitted, it may default to common system Python paths.

pycompile is a utility used to byte-compile Python source files (.py) into bytecode files (.pyc, or .pyo for optimized versions). This process improves the startup time of Python applications and reduces the need for source code distribution.

It primarily works by locating Python source files within specified paths and invoking the appropriate Python interpreter with its built-in compilation modules (like py_compile or compileall). While pycompile can be run manually, its most common use case is within Debian-based packaging systems, particularly by maintainer scripts like dh_python3 or dh_python2. It ensures that system-wide Python installations or distributed packages include pre-compiled bytecode, optimizing performance and adherence to system standards. It handles different Python versions and manages the creation and removal of bytecode files, including those in __pycache__ directories for Python 3.

pycompile is primarily a utility within the Debian/Ubuntu ecosystem for managing Python bytecode during package installation and removal. It may not be available or function identically on other Linux distributions. Users should ensure they have write permissions in the directories where bytecode files are to be created or removed. Misuse can lead to unnecessary recompilations or removal of valid bytecode.

Python bytecode (.pyc files) is an intermediate, platform-independent representation of Python source code. When a .py file is first imported, Python compiles it into bytecode and caches it. Subsequent imports skip the compilation step, leading to faster startup times. pycompile automates this process for system-wide or packaged Python code, ensuring that the performance benefits are realized without manual intervention. The -O and -OO flags allow for further optimization by removing docstrings and assertions, reducing the size of bytecode files, which can be beneficial in resource-constrained environments.

For Python 3, bytecode files are typically stored in a subdirectory named __pycache__ located within the package directory. For example, module.py will have its bytecode stored as __pycache__/module.cpython-3x.pyc. This structure helps keep the main package directory clean and supports multiple Python versions by including version-specific tags in the bytecode filename. pycompile correctly manages these __pycache__ directories, including their creation, update, and removal.

pycompile emerged as a crucial component of Debian's Python packaging infrastructure. Its development aimed to standardize the byte-compilation of Python modules across system installations, ensuring efficient execution and proper dependency management. It evolved significantly with the transition from Python 2 to Python 3, adapting to changes like the introduction of the __pycache__ directory for Python 3 bytecode and handling multiple Python versions concurrently on a single system.

python(1), dh_python3(1), dh_python2(1), python -m compileall(1)