pyclean

pyclean [OPTIONS] [dir_or_file ...]

-V, --version
    Print the version number and exit.

-v, --verbose
    Turn on verbose messages, listing each processed file and directory.

-d, --dry-run
    Perform a dry run without actual file removal, useful for testing.

-p, --path
    Walk through all directories in sys.path and remove byte-compiled files. This also enables -f by default.

-i, --interactive
    Ask for confirmation before removing files.

-k, --keep-cache-dir
    Do not remove __pycache__ directories. This option implies -X __pycache__.

-r, --recursive
    Recursively walk the directories given on the command line. This is the default if no directories are provided.

-q, --quiet
    Turn off all messages, overriding verbose output.

-f, --force
    Force removal of all byte-compiled files, even if not writable (useful for root).

-X, --exclude=PATTERN
    Exclude files or directories matching PATTERN from consideration. This option can be used multiple times.

dir_or_file ...
    One or more directories or files to process. If no arguments are given, pyclean will recursively walk the current directory.

pyclean is a utility designed to clean up Python source trees by removing byte-compiled .pyc and .pyo files. For Python 3.2 and newer versions, it also cleans up __pycache__ directories, which store bytecode files in a structured manner. These generated files are typically created when Python scripts are executed and serve to speed up subsequent executions by avoiding recompilation. While beneficial for performance, they can clutter development directories, especially across different Python versions or when changing code frequently. pyclean helps maintain a clean source tree, making it easier to manage code, distribute projects without unnecessary compiled artifacts, and avoid potential issues caused by stale bytecode. It can operate on specified directories or recursively clean the current directory by default, providing options for verbose output, dry runs, interactive deletion, and exclusion patterns. This command is particularly useful in development environments, build systems, or packaging processes where temporary build artifacts need to be cleared efficiently.

pyclean can remove files that are not strictly necessary for running Python applications but are useful for performance.
Using the --force option can remove files even if they are not writable, which should be used with caution, especially when running as root.
Care should be taken when using --path as it affects all directories in the Python sys.path, potentially cleaning system-wide or site-packages directories if not careful.

The pyclean utility is primarily associated with Debian-based Linux distributions, developed by Thomas Viehmann. It was greatly inspired by the earlier `pycentral` utility, which also dealt with managing Python bytecode files. Its development focuses on providing a convenient and integrated way to clean up Python environments within the Debian ecosystem, adapting to changes in Python's bytecode caching mechanisms (e.g., the introduction of __pycache__ directories in Python 3.2).

python(1), python(1p), python-cached-scripts(7)