pyclean

3.6.0 · active · verified Thu Apr 16

pyclean is a pure Python, cross-platform utility designed to clean up Python bytecode files (.pyc, .pyo) and `__pycache__` directories. Beyond bytecode, it also targets debris generated by popular Python development tools such as cache files, build artifacts, and testing-related data (e.g., from Coverage, Pytest, Ruff, Jupyter, Mypy, Pyright, Tox). It aims to provide a single, consistent command for cleanup across different operating systems, inspired by Debian's original `pyclean` scripts. The current version is 3.6.0, with ongoing active development and recent releases.

Common errors

```
No command 'pyclean' found, did you mean: ...
```
cause The `pyclean` executable is not in your system's PATH, or the package was not installed correctly in your active environment.

fix Ensure `pyclean` is installed with `pip install pyclean`. If installed in a virtual environment, activate the environment. You can also try running it explicitly with `python -m pyclean .` to bypass PATH issues.
```
Files unexpectedly deleted or permission denied during cleanup with --erase.
```
cause The `--erase` option was used with incorrect glob patterns or without `--dry-run`, leading to unintended file deletions, or `pyclean` lacked the necessary file system permissions.

fix Always use `pyclean <target> --dry-run --erase` first to confirm what will be removed. Ensure `pyclean` is run with appropriate permissions for the directories it needs to clean (e.g., using `sudo` on Linux/macOS for system-wide directories, or by being the file owner).
```
Unexpected module behavior, old code running despite source changes (stale bytecode).
```
cause Python is loading stale `.pyc` files from `__pycache__` directories or old `.pyc` files left in sibling directories, rather than the updated `.py` source code. This can happen after switching Git branches or manually deleting source files.

fix Run `pyclean .` in your project's root directory to remove all bytecode and `__pycache__` directories, forcing Python to regenerate fresh bytecode from your current source files.

Warnings

breaking Using the `--erase` option can lead to irreversible data loss. This option allows deletion of arbitrary file system objects via globbing and does not perform recursive deletion by itself, requiring explicit paths for directories and their contents. Always use `--dry-run` first.
Fix: Before using `--erase`, run `pyclean --erase <target> --dry-run` to review exactly what will be deleted. Be extremely cautious and explicit with paths.
gotcha This `pyclean` PyPI package is a cross-platform re-implementation and differs from the `pyclean` (and `py3clean`) commands bundled with Debian-based Linux distributions. The Debian versions have different behaviors, especially regarding package-specific cleaning.
Fix: Ensure you are using the `pyclean` installed via pip (or `python -m pyclean`) if you intend to use the features of this cross-platform tool. If targeting Debian package-specific cleanup, use the system-provided `pyclean`.
gotcha The `--git-clean` (or `-g`) flag integrates with `git clean` to remove untracked files. This functionality requires Git to be installed and accessible in your system's PATH. If Git is not present, this option will not work and a warning will be logged.
Fix: Install Git on your system if you wish to use the `--git-clean` feature. Refer to your operating system's documentation for Git installation instructions.
gotcha Removing `.pyc` files and `__pycache__` directories is generally safe as Python regenerates them automatically on import. However, the first import after cleaning might experience a brief slowdown due to the regeneration process.
Fix: No fix needed, this is expected behavior. If performance is critical immediately after a clean, consider running a quick import of your main modules to pre-generate bytecode.

Install

pip install pyclean Install from PyPI
conda install conda-forge::pyclean Install with Conda

Quickstart

pyclean is primarily a command-line utility. To clean up bytecode files and `__pycache__` directories in the current directory and its subdirectories, simply run `pyclean .`. You can add `--debris` to also clean up other development tool artifacts. The `--dry-run` option is highly recommended to preview changes before execution.

# Clean up all bytecode in the current directory tree
pyclean .

# Dry-run a cleanup of bytecode and tool debris in verbose mode
# (to see what would be deleted without actually deleting it)
pyclean . --debris --verbose --dry-run

view raw JSON →