cleanpy

cleanpy is an architecture-aware CLI to simplify Python cleanup on macOS.

It answers three questions in one run:

• What Python installs exist right now?
• What should be removed?
• What should be installed after cleanup?

Quick start

poetry install
poetry run cleanpy

Commands

# Dry run (default)
poetry run cleanpy

# Apply auto-safe symlink removals (asks for confirmation)
poetry run cleanpy --apply

# Apply without prompt
poetry run cleanpy --apply --yes

# Machine-readable output
poetry run cleanpy --json

Example output

Dry run

$ poetry run cleanpy
cleanpy architecture-aware Python cleanup
Host architecture: arm64
Rosetta translated shell: no
Preferred architecture target: arm64

Required versions (from project files): 3.12

Installed now
- /opt/homebrew/bin/python3        3.14.3  arm64  homebrew
- /opt/homebrew/bin/python3.13     3.13.5  arm64  homebrew
- /usr/bin/python3                 3.9.6   universal2  system

Remove
- /usr/local/bin/python3
  Reason: Intel Homebrew Python on Apple Silicon.
  Auto apply: yes

Install after cleanup
- 3.12 -> brew install python@3.12
  Reason: Referenced by project files but missing after cleanup.

Run poetry run cleanpy --apply to apply safe symlink removals.

Apply mode

$ poetry run cleanpy --apply --yes
...
Applied removals: 1
  - /usr/local/bin/python3
Skipped actions: 0

Install after cleanup:
  - brew install python@3.12  # Referenced by project files but missing after cleanup.

Notes

• Architecture is auto-detected (arm64 vs x86_64) and Rosetta state is shown.
• System Python under /usr/bin is never removed.
• --apply currently auto-removes only safe symlink candidates. Other removals are shown with manual commands.