pyclean

What it is and what it does

PyClean is a command-line utility that removes Python bytecode artifacts (.pyc files and __pycache__ directories) from your project tree in a single, cross-platform command. It addresses the common problem of bytecode clutter that accumulates during development, especially when switching between Python versions or working across different operating systems. Unlike shell commands like `rm` or `find`, PyClean provides a safe, intentional interface with options for dry-run preview, verbose output, and interactive confirmation.

Beyond bytecode cleanup, PyClean can optionally remove debris from popular development tools (pytest, coverage, ruff, mypy, tox, and others) in their default locations, detect and remove empty directories left after refactoring, and integrate with Git's `git clean` command. It supports globbing for arbitrary file deletion with safety constraints to prevent accidental data loss. The tool is actively maintained, supports modern Python versions (3.9–3.14), runs on both CPython and PyPy, and has no runtime dependencies.

Use it for:

• Clean bytecode before committing to version control to avoid merge conflicts from .pyc file changes.
• Remove accumulated __pycache__ directories and tool caches after switching Python versions or development environments.
• Integrate into tox or CI/CD pipelines as a pre-test cleanup step via the --debris flag.
• Safely delete arbitrary project files using glob patterns with the --erase option and dry-run preview.
• Detect and remove empty directories left behind after code refactoring with the --folders flag.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Removes Python bytecode files (.pyc) and __pycache__ directories across your project in a single command, with optional cleanup of tool debris and empty directories.

Yes. PyClean solves a genuine cross-platform problem with zero dependencies, active maintenance, and a clear safety-first design. The copyleft license is a minor consideration for development tools but not a blocker for most projects. Install it if you work in multi-version Python environments or want a safer alternative to shell commands for bytecode cleanup.

Install

pyclean on PyPI

pip install pyclean

uv add pyclean

poetry add pyclean

Installing pyclean

Before you install

Low friction install with no runtime dependencies. Actively maintained as of 2026-05-23 with 91 repository stars. Supports Python 3.9 through 3.14 and both CPython and PyPy implementations.

License in practice

Licensed under GPL-3.0-or-later (copyleft). Requires derivative works and modifications to be distributed under the same license; suitable for development tools but check your project's licensing compatibility before integrating.

Quickstart

pip install pyclean
pyclean --help
pyclean -v .

Requires Python 3.9 or later. Git must be installed if using the --git-clean feature.

Verify before relying

• Whether the --erase option's safety constraints (no recursive deletion by default, interactive confirmation) are sufficient for production use cases.
• Performance characteristics when cleaning very large project trees or deeply nested directory structures.

Package facts

Evidence: pyclean-3.7.0-py3-none-any.whl

Keywords: python, bytecode, cli, tools

Tags

More Utilities packages