Pre-installed Python conflicts with Homebrew Python on macOS

[bebound]

Description

In macOS 12 and 13, it has pre-installed Python /Library/Frameworks/Python.framework/Versions/3.xx/, which creates soft link such as /usr/local/bin/2to3-3.xx. Homebrew's [email protected] also wants to create this link.

This causes issue when there is new Python is released, and brew install xx tries to install the latest Python: see https://github.com/Homebrew/homebrew-core/issues/165793#issuecomment-1989441193

Runner image has a fix for Python 2.7: https://github.com/actions/runner-images/blob/9d5d1be4828f3f7e54796a46d60afd0a2f9e05b0/images/macos/scripts/build/install-python.sh#L17-L25 It used to let brew overwrite the [email protected] soft link to resolve the conflict, but is removed in https://github.com/actions/runner-images/pull/8452/files#diff-5490845eec9cd46fa52e10c62bd6ec6a76c27f17a338963a508414efd8b2252dR33-R34

Now I have to run brew unlink [email protected] && brew link --overwrite [email protected] before using brew install xxx to eliminate the potential conflict. It's tedious.

There is a PR attempting to address this issue: https://github.com/actions/runner-images/pull/7710, but it was rejected. Regardless of whether the fix should be implemented in actions/setup-python, we are still facing this issue one year later. I believe the runner image should consider providing a temporary fix for this.

Related issue: https://github.com/Homebrew/homebrew-core/issues/173191 https://github.com/Azure/azure-cli/issues/29054

Platforms affected

• [X] Azure DevOps
• [X] GitHub Actions - Standard Runners
• [ ] GitHub Actions - Larger Runners

Runner images affected

• [ ] Ubuntu 20.04
• [ ] Ubuntu 22.04
• [ ] Ubuntu 24.04
• [ ] macOS 11
• [X] macOS 12
• [X] macOS 13
• [ ] macOS 13 Arm64
• [ ] macOS 14
• [ ] macOS 14 Arm64
• [ ] Windows Server 2019
• [ ] Windows Server 2022

Image version and build link

This could be reproduced by reinstalling [email protected]

brew uninstall azure-cli
brew install [email protected]

https://github.com/bebound/starter-workflows/actions/runs/9298969591/job/25591905178

Is it regression?

Yes?

Expected behavior

Successfully install [email protected] with brew.

Actual behavior

Pouring [email protected]
Error: The `brew link` step did not complete successfully
Error: The `brew link` step did not complete successfully
The formula built, but is not symlinked into /usr/local
Could not symlink bin/2to3-3.[11](https://github.com/bebound/starter-workflows/actions/runs/9298969591/job/25591905178#step:7:12)
Target /usr/local/bin/2to3-3.11
already exists. You may want to remove it:
  rm '/usr/local/bin/2to3-3.11'

To force the link and overwrite all conflicting files:
  brew link --overwrite [email protected]

To list all files that would be deleted:
  brew link --overwrite [email protected] --dry-run

Possible conflicting files are:
/usr/local/bin/2to3-3.11 -> /Library/Frameworks/Python.framework/Versions/3.11/bin/2to3-3.11
/usr/local/bin/idle3.11 -> /Library/Frameworks/Python.framework/Versions/3.11/bin/idle3.11
/usr/local/bin/pydoc3.11 -> /Library/Frameworks/Python.framework/Versions/3.11/bin/pydoc3.11
/usr/local/bin/python3.11 -> /Library/Frameworks/Python.framework/Versions/3.11/bin/python3.11
/usr/local/bin/python3.11-config -> /Library/Frameworks/Python.framework/Versions/3.11/bin/python3.11-config

Repro steps

brew uninstall azure-cli brew install [email protected]

[Alexey-Ayupov]

Hello @bebound, this issue should be fixed after the next image release.

[bebound]

@Alexey-Ayupov May I know which PR fixes this?

[erik-bershel]

Hello @bebound !

A little (not exactly true 😄) clarification. @Alexey-Ayupov meant that the problem would resolve itself with updating the macOS images until Homebrew released dependency updates. Unfortunately this problem lies between setup-python and Homebrew - their packages conflict due to the paths used as @cho-m mentioned. Hypothetically, we could change the path, which would remove the problem for Homebrew users, but would break users of the setup-python action for some scenarios. Unfortunately, the most complete solution to this problem “forever” would be to remove the Python packages from the image in order to install it during runtime from specific source by customers, which is a bit irrational. Relinking is always easier than reinstalling.

We will do some more research on what can be done in a way not to break existed workflows and welcome any ideas from you as a user.

[bebound]

I prefer let homebrew overwrite setup-python for two reasons:

1. Homebrew is more likely to trigger the conflict as it always checks for new version, and it's hard to debug when brew install fails suddenly because Python release a new version.
2. It's more explicit/efficient to resolve the conflict when users use setup-python than use Brew to install packages depending on python@xxx.

Also, if this possible to pre-install brew's python@xx to replace setup-python on macOS?

Out of curiosity, which line creates the soft link from /usr/local/bin/python3.11 to /Library/Frameworks/Python.framework/Versions/3.11/bin/python3.11?

[QuLogic]

It seems like this is slowly rolling out to more runners.

[QuLogic]

Oh, and it's back again now that Homebrew released Python 3.12.5, but the images are on an older version. It's also affecting both Azure and GitHub Actions now.

The annoying thing is that we aren't even using the Homebrew Python, but the one from setup-python/UsePythonVersion. But one of our system dependencies (installed via Homebrew) does, and so we have this conflict arise for something we don't really use.

[janbrasna]

The fix for GHA env got stale on Homebrew side unfortunately:

• https://github.com/Homebrew/brew/pull/18612

[traversaro]

xref to the issue https://github.com/actions/runner-images/issues/11545, that was opened in this repo to track this problem but then was moved to setup-python.

[sureshe456]

Hi @bebound Please be aware that macOS 12 runner is now deprecated and is currently not  under support.

We understand that you may encounter conflicts with Python installations on macOS. Specifically, macOS creates symbolic links (soft links) in /usr/local/bin that point to its system Python installation. This can conflict with Homebrew's Python, as both systems attempt to manage the same directory. This conflict is further complicated by macOS's System Integrity Protection (SIP), which restricts modifications to system files.

The latest Python versions are now available in macOS 13 intel runner, and you can use them. follow this link for more information.

Please let us know if any further queries. Thanks.

[bebound]

This issue persists on macOS. Homebrew always tries to use the latest dependency. If you try to install a Homebrew package that requires Python and a newer version of Python is released than the pre-installed one, the command fails. This makes the brew install command unpredictable.

[sureshe456]

Hi @bebound We will dig into this issue more and keep you posted on any updates.Thanks.

[sureshe456]

Hi All, We are still analysing to find out python package manager how it works.We will keep you posted if there are any updates. Thanks for your patience.

[jackjansen]

I'm glad I finally found this issue! For us the situation was even more obscure, because we were not installing [email protected] ourselves, but it was a dependency from some other brew formula...

[sureshe456]

Hi All, We are still investigating the issue and working on providing a workaround to resolve it. we will keep you updated with any progress.

Thank you for your patience.

[kintel]

While waiting for an official solution or workaround from GitHub, can anyone recommend alternative CI solutions with better macOS support? CircleCI comes to mind, but curious what other products people find to offer good support these days.

[sureshe456]

Hi @bebound,

The symlink conflict on Intel-based macOS images begining from our transition (after Python 3.11) to using Python.org installers in the toolcache. These installers place symlinks in /usr/local/bin, which overlap with Homebrew's paths. As a result, issues arise when users install or upgrade Python via Homebrew, particularly when Python is a dependency of other packages. We will not make changes to the current Intel-based images, as the severity is low and the images need to maintain lightweight. We will explore transitioning setup-python to use Homebrew on macOS (and apt on Ubuntu), starting with macos-16 images.

Thank you and appreciate your patience.