{"id":7551,"library":"pyclean","title":"pyclean","description":"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.","status":"active","version":"3.6.0","language":"en","source_language":"en","source_url":"https://github.com/bittner/pyclean","tags":["cli","utility","cleanup","bytecode","cache","build-tools","cross-platform"],"install":[{"cmd":"pip install pyclean","lang":"bash","label":"Install from PyPI"},{"cmd":"conda install conda-forge::pyclean","lang":"bash","label":"Install with Conda"}],"dependencies":[],"imports":[],"quickstart":{"code":"# Clean up all bytecode in the current directory tree\npyclean .\n\n# Dry-run a cleanup of bytecode and tool debris in verbose mode\n# (to see what would be deleted without actually deleting it)\npyclean . --debris --verbose --dry-run","lang":"bash","description":"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."},"warnings":[{"fix":"Before using `--erase`, run `pyclean --erase <target> --dry-run` to review exactly what will be deleted. Be extremely cautious and explicit with paths.","message":"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.","severity":"breaking","affected_versions":">=3.0.0"},{"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`.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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.","cause":"The `pyclean` executable is not in your system's PATH, or the package was not installed correctly in your active environment.","error":"No command 'pyclean' found, did you mean: ..."},{"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).","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.","error":"Files unexpectedly deleted or permission denied during cleanup with --erase."},{"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.","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.","error":"Unexpected module behavior, old code running despite source changes (stale bytecode)."}]}