Troubleshooting: "Error: The brew link step did not complete successfully" When Installing Python

Problem

When installing a Homebrew package that depends on Python 3, or when installing Python 3 itself, you may encounter this error:

Error: The `brew link` step did not complete successfully
The formula built, but is not symlinked into /usr/local
Could not symlink Frameworks/Python.framework/Headers
Target /usr/local/Frameworks/Python.framework/Headers
is a symlink belonging to python@2.

This error occurs because Homebrew removed Python 2 from its repository in February 2020. Previously, Python 3 was linked as "python3", but now it links as "python", which conflicts with any remaining Python 2 symlinks on your system.

Solution

Before installing any Homebrew packages, unlink Python 2:

brew unlink python@2

After running this command, proceed with installing your Homebrew package.

Outcome

After unlinking Python 2, the brew link step will complete successfully, and Python 3 will be properly symlinked as "python" in your system.

If you continue to experience linking errors after following this solution, contact CircleCI Support.

Additional Notes

Important: Starting with Xcode 11.4, CircleCI no longer includes Python 2 in macOS executor images. This aligns with Homebrew's removal of Python 2 support.

Additional Resources

• Using macOS Executors - Learn about macOS build environments on CircleCI
• Homebrew and Python Documentation - Official Homebrew Python guidelines