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

When installing a Homebrew package that depends on Python 3, or when installing Python 3 itself, you may run in to the following 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 due to the removal of Python 2 from Homebrew. Previously, Python 3 would be linked as "python3", but now it will be linked as "python" which overrides the previous Python 2 version.

If you receive this error, you will need to add the following step before installing any Homebrew packages:

- run: brew unlink python@2

Note: From the Xcode 11.4 image onwards, we no longer ship Python 2 with the image.