pyclean

library3.6.0pypypiunverified

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.

devops testing

pip install pyclean

github ↗package ↗

INSTALL

IMPORT

SIG · PYCLEAN

pyclean

devopspythonv3.6.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

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

pyclean --version

Debug

Known issues

breakingUsing 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.

affects: >=3.0.0

gotchaThis `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`.

affects: All versions

gotchaThe `--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.

affects: All versions

gotchaRemoving `.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.

affects: All versions

Errors

Common errors & fixes

No command 'pyclean' found, did you mean: ...

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.

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).

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.

Upgrade

Version history

3.6.0latest on PyPI · released Mar 30, 2026

Audit

Dependencies

No dependency data recorded yet.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/bittner/pyclean ↗

packagehttps://pypi.org/project/pyclean/ ↗