Cleanly removing "Broken" Python symlinks on macOS Sonoma after a Homebrew update

Developer Environment Hell

Setting up a machine to code is often significantly harder than the coding itself. On macOS, the collision between the system's pre-installed Python, Homebrew python installations, and virtual environments can result in a completely shattered terminal experience.

If you ran brew upgrade and suddenly typing python3 yields command not found or points to a non-existent directory, your symlinks are broken.

# The Anatomy of the Broken Link

When Homebrew updates Python (e.g., from 3.11 to 3.12), it removes the old binaries. However, old symlinks in /usr/local/bin or /opt/homebrew/bin might still point to the deleted version.

# The Clean Cleanup

Don't just randomly delete files with sudo. Let's fix this methodically.

1. Find where your terminal thinks python is: which python3 It will likely return a path that is currently dead.

2. Clean Homebrew's symlinks: Run the following command to have Homebrew prune dead links: brew cleanup

3. Force a re-link of Python: Tell Homebrew to explicitly overwrite the symlinks for its current Python version: brew link --overwrite python@3.12 (Change 3.12 to your installed version)

4. Verify your PATH variable: Ensure that /opt/homebrew/bin (for Apple Silicon) is at the very front of your $PATH in your ~/.zshrc file.

If you are tired of local environment issues, it might be time to Dockerize your apps. Enjoy a stable shell again! Check out this YouTube crash course on macOS PATH variables to truly master your environment.