pyclean

Worried about .pyc files and __pycache__ directories? Fear not! PyClean is here to help. Finally, the single-command clean up for Python bytecode files in your favorite directories. On any platform.

Presented at PyConX, Firenze 2019.

Wait! What is bytecode?

Bytecode is opcodes for the Python Virtual Machine. -- Confused?

If you want to deep-dive into the topic watch the 2013 EuroPython talk "All Singing All Dancing Python Bytecode" by Larry Hastings. Otherwise James Bennett's "Introduction to Python bytecode" should provide you with just the sound understanding of what it is all about.

Why not simply use rm **/*.pyc or find -name '*.py?' -delete?

If you're happy with rm or find, go for it! When I was looking for a simple, concise solution for everybody I figured people are struggling, and simple things are more complicated than they appear at first sight.

Also, there is a pyclean command (and its siblings) on Debian. And, well, only on Debian as it turns out. Not that I'm a big fan of Mircosoft Windos, but why ignore the biggest Python population on this planet? (As if they weren't punished enough already using this unfree piece of software!)

Inspired by Debian

On a nostalgic note, PyClean is somewhat the brainchild of Debian Python package maintenance. The Python scripts Debian ships with its python-minimal and python3-minimal packages can be found at:

• pyclean: salsa.debian.org/cpython-team/python-defaults
• py3clean: salsa.debian.org/cpython-team/python3-defaults
• pypyclean: salsa.debian.org/debian/pypy

Alternatives

PyClean tries to make your cleanup experience as convenient and safe as possible, but if you really can't live with using it, the only valid cross-platform alternative for you as a developer is probably git-clean, e.g.

git clean -dfx -e .idea -e .vscode -n

Installation 🧑‍💻

pip install pyclean

or

python -m pip install pyclean

uv

If you work with uv you can install pyclean globally via uv's tool interface and use it like a system command:

uv tool install pyclean
pyclean

Or simply use the uvx command and don't care about installing at all:

uvx pyclean

Conda

conda install conda-forge::pyclean

Tox

If you want to integrate pyclean in your Python development setup you can add it to your tox.ini file as follows:

[testenv:clean]
skip_install = true
deps = pyclean
commands = pyclean {posargs:. --debris}

You'll then be able to run it with Tox like this:

tox -e clean

Usage ✨

pyclean --help

or

python -m pyclean --help

Clean up all bytecode in the current directory tree, and explain verbosely:

pyclean -v .

Clean up debris 💩

PyClean can clean up leftovers, generated data and temporary files from popular Python development tools in their default locations, along with Python bytecode. The following topics are currently covered:

• Cache (general purpose folder for several tools, e.g. Python eggs, legacy Pytest)
• Coverage (coverage database, and supported file formats)
• Packaging (build files and folders)
• Pytest (build files and folders)
• Ruff (ruff cache folder)
• Jupyter (notebook checkpoints) – optional
• Mypy (mypy cache folder) – optional
• Pyright (pyright app cache folder) – optional
• Tox (tox environments) – optional

Example: Dry-run a cleanup of bytecode and tool debris in verbose mode (to see what would be deleted):

pyclean . --debris --verbose --dry-run

Arbitrary file system objects 🐊

PyClean also lets you remove free-form targets using globbing. Note that this is potentially dangerous: You can delete everything anywhere in the file system, including the entire project you're working on. For this reason, the --erase option has a few artificial constraints:

• It doesn't do recursive deletion by itself, which means that you have to specify the directory and its contents, separately and explicitly.
• The above entails that you're responsible for the deletion order, i.e. removal of a directory will only work if you asked to delete all files inside first.
• You're prompted interactively to confirm deletion, unless you specify the --yes option, in addition.

pyclean . --erase tmp/**/* tmp/

The above would delete the entire tmp/ directory with all subdirectories inside the current folder. If you omit the final tmp/ you'll leave the empty tmp directory in place. (WARNING! Don't put the . after the --erase option! Obviously, your project files will all be deleted.)

Empty directories 📂

PyClean can safely detect and remove empty directories that are left in your project after refactoring code.

pyclean . --folders --verbose

Git-clean integration 🏷️

PyClean integrates with Git's git clean command to remove untracked files from version-controlled directories. The --git-clean (or -g) flag runs after all other cleanup operations.

By default, Git prompts interactively to confirm which files to delete. Use --dry-run to preview, or --yes to force deletion without prompts. The --ignore patterns are honored as exclusions.

pyclean . --debris all --git-clean --dry-run

pyclean . --ignore .idea .vscode --git-clean --yes

Note: Git must be installed for this feature. If a directory is not under version control, a warning is logged and pyclean continues.

Development

If you want to help out please see our contribution guide.