File overwrite errors when installing Python 3.13 on MacOS

[savannahostrowski]

brew gist-logs <formula> link OR brew config AND brew doctor output

HOMEBREW_VERSION: 4.4.2
ORIGIN: https://github.com/Homebrew/brew
HEAD: 35ebf4a047b00b2b3de33ba0081d71293cdadede
Last commit: 2 days ago
Core tap HEAD: 433867966e8fa2f684fe2ada33002c6a0a69e2e1
Core tap last commit: 32 minutes ago
Core tap JSON: 22 Oct 23:03 UTC
Core cask tap HEAD: fc7baf0b4485f90ff12ba33495cb2fbde69f2425
Core cask tap last commit: 27 minutes ago
Core cask tap JSON: 22 Oct 23:03 UTC
HOMEBREW_PREFIX: /usr/local
HOMEBREW_CASK_OPTS: ["--no-quarantine"]
HOMEBREW_COLOR: set
HOMEBREW_MAKE_JOBS: 4
HOMEBREW_NO_AUTO_UPDATE: set
HOMEBREW_NO_INSTALL_CLEANUP: set
Homebrew Ruby: 3.3.5 => /usr/local/Homebrew/Library/Homebrew/vendor/portable-ruby/3.3.5/bin/ruby
CPU: quad-core 64-bit ivybridge
Clang: 15.0.0 build 1500
Git: 2.47.0 => /usr/local/bin/git
Curl: 8.7.1 => /usr/bin/curl
macOS: 13.7-x86_64
CLT: 14.3.1.0.1.1683849156
Xcode: 15.2 => /Applications/Xcode_15.2.app/Contents/Developer

Verification

• My brew doctor output says Your system is ready to brew. and am still able to reproduce my issue.
• I ran brew update and am still able to reproduce my issue.
• I have resolved all warnings from brew doctor and that did not fix my problem.
• I searched for recent similar issues at https://github.com/Homebrew/homebrew-core/issues?q=is%3Aissue and found no duplicates.

What were you trying to do (and why)?

I work on CPython and, specifically, our JIT compiler. As part of our workflow to build and test JIT-enabled builds, we install Python via setup-python and llvm via Homebrew for macos builds. While LLVM has a transitive dependency on Python, we previously had no issues with this workflow.

However, it seems like the default Python version of Homebrew was recently updated to 3.13 and some changes were made to the 3.12 formula (via #182840), and Homebrew may no longer be handling overwriting files as it once did. On recent runs (see this run for example), we are now seeing errors related to overwriting files related to this transitive dependency LLVM has on Python 3.13.

Although I'm running into this in a pipeline, I'd suspect that a user could run into this in their local environment if they have 3.12 installed and then try to brew install [email protected]...or they install a package that depends on it (for example).

What happened (include all command output)?

Run brew update
==> Updating Homebrew...
==> Homebrew's analytics have entirely moved to our InfluxDB instance in the EU.
We gather less data than before and have destroyed all Google Analytics data:
  https://docs.brew.sh/Analytics
Please reconsider re-enabling analytics to help our volunteer maintainers with:
  brew analytics on
==> Homebrew is run entirely by unpaid volunteers. Please consider donating:
  https://github.com/Homebrew/brew#donations

Updated 5 taps (hashicorp/tap, homebrew/bundle, aws/tap, homebrew/core and homebrew/cask).
==> New Formulae
ansible-builder
clickhouse-sql-parser
distill-cli
hawkeye
kubetail
[email protected]
minijinja-cli
[email protected]
[email protected]
[email protected]
recc
sf
termscp
tex-fmt
zsh-system-clipboard
==> New Casks
ableset
adlock
anytype@alpha
anytype@beta
backyard-ai
bentobox
cap
displaybuddy
follow
follow@nightly
font-doto
font-faculty-glyphic
font-host-grotesk
font-mynaui-icons
imaging-edge
legcord
lets
magicquit
mailbird
morisawa-desktop-manager
quba
singlebox
thunderbird@esr
unraid-usb-creator-next
webkinz
==> Outdated Formulae
aws-sam-cli
azure-cli
bazelisk
c-ares
certifi
cffi
cmake
cryptography
gh
glib
kotlin
libssh2
libuv
openexr
perl
pycparser
python-packaging
[email protected]
swiftformat
unbound
xcbeautify
==> Outdated Casks
session-manager-plugin

You have 21 outdated formulae and 1 outdated cask installed.
You can upgrade them with brew upgrade
or list them with brew outdated.
==> Downloading https://ghcr.io/v2/homebrew/core/llvm/manifests/19.1.2
==> Fetching dependencies for llvm: [email protected] and z3
==> Downloading https://ghcr.io/v2/homebrew/core/python/3.13/manifests/3.13.0_1
==> Fetching [email protected]
==> Downloading https://ghcr.io/v2/homebrew/core/python/3.13/blobs/sha256:d5257cc367cea5fb1003646077cdb644e8eb181045e2815255738242e05f8af2
==> Downloading https://ghcr.io/v2/homebrew/core/z3/manifests/4.13.3
==> Fetching z3
==> Downloading https://ghcr.io/v2/homebrew/core/z3/blobs/sha256:8819a26a9[16](https://github.com/python/cpython/actions/runs/11453246712/job/31865589688?pr=125499#step:6:17)5a9e2e309d07a32db67e4f6d12eea025c87fa2d35c588b9393b85
==> Fetching llvm
==> Downloading https://ghcr.io/v2/homebrew/core/llvm/blobs/sha256:5a218d82a37c5983a73fec61826278e49e7788e72131ca01b1808c0bcac4ba8f
==> Installing dependencies for llvm: [email protected] and z3
==> Installing llvm dependency: [email protected]
==> Downloading https://ghcr.io/v2/homebrew/core/python/3.13/manifests/3.13.0_1
Already downloaded: /Users/runner/Library/Caches/Homebrew/downloads/9b[17](https://github.com/python/cpython/actions/runs/11453246712/job/31865589688?pr=125499#step:6:18)bb2e9c677d8c64b5adc51ee37d3de0d768a86fc8a8526255a2bf36aeb114--python@3.13-3.13.0_1.bottle_manifest.json
==> Pouring [email protected]_1.ventura.bottle.tar.gz
Error: The `brew link` step did not complete successfully
The formula built, but is not symlinked into /usr/local
Could not symlink bin/idle3
Target /usr/local/bin/idle3
already exists. You may want to remove it:
  rm '/usr/local/bin/idle3'

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/idle3 -> /Library/Frameworks/Python.framework/Versions/3.12/bin/idle3
/usr/local/bin/pydoc3 -> /Library/Frameworks/Python.framework/Versions/3.12/bin/pydoc3
/usr/local/bin/python3 -> /Library/Frameworks/Python.framework/Versions/3.12/bin/python3
/usr/local/bin/python3-config -> /Library/Frameworks/Python.framework/Versions/3.12/bin/python3-config
/usr/local/share/man/man1/python3.1 -> /usr/local/Cellar/[email protected]/3.12.7/share/man/man1/python3.1
/usr/local/lib/pkgconfig/python3-embed.pc -> /usr/local/Cellar/[email protected]/3.12.7/lib/pkgconfig/python3-embed.pc
/usr/local/lib/pkgconfig/python3.pc -> /usr/local/Cellar/[email protected]/3.12.7/lib/pkgconfig/python3.pc
/usr/local/Frameworks/Python.framework/Headers -> /usr/local/Cellar/[email protected]/3.12.7/Frameworks/Python.framework/Headers
/usr/local/Frameworks/Python.framework/Python -> /usr/local/Cellar/[email protected]/3.12.7/Frameworks/Python.framework/Python
/usr/local/Frameworks/Python.framework/Resources -> /usr/local/Cellar/[email protected]/3.12.7/Frameworks/Python.framework/Resources
/usr/local/Frameworks/Python.framework/Versions/Current -> /usr/local/Cellar/[email protected]/3.12.7/Frameworks/Python.framework/Versions/Current
==> /usr/local/Cellar/[email protected]/3.13.0_1/bin/python3.13 -Im ensurepip
==> /usr/local/Cellar/[email protected]/3.13.0_1/bin/python3.13 -Im pip install -v --n
==> Summary
🍺  /usr/local/Cellar/[email protected]/3.13.0_1: 3,253 files, 63.2MB
==> Installing llvm dependency: z3
==> Downloading https://ghcr.io/v2/homebrew/core/z3/manifests/4.13.3
Already downloaded: /Users/runner/Library/Caches/Homebrew/downloads/1af4f888971692e5699871ec914b60ac85d639ebbeea996ffb929c014802e6f6--z3-4.13.3.bottle_manifest.json
==> Pouring z3--4.13.3.ventura.bottle.tar.gz
🍺  /usr/local/Cellar/z3/4.13.3: 120 files, 32.4MB
==> Installing llvm
==> Pouring llvm--[19](https://github.com/python/cpython/actions/runs/11453246712/job/31865589688?pr=125499#step:6:20).1.2.ventura.bottle.tar.gz
==> Caveats
LLD is now provided in a separate formula:
  brew install lld

We plan to build LLVM [20](https://github.com/python/cpython/actions/runs/11453246712/job/31865589688?pr=125499#step:6:21) with `LLVM_ENABLE_EH=OFF`. Please see:
  https://github.com/orgs/Homebrew/discussions/5654

To use the bundled libunwind please use the following LDFLAGS:
  LDFLAGS="-L/usr/local/opt/llvm/lib/unwind -lunwind"

To use the bundled libc++ please use the following LDFLAGS:
  LDFLAGS="-L/usr/local/opt/llvm/lib/c++ -L/usr/local/opt/llvm/lib/unwind -lunwind"

NOTE: You probably want to use the libunwind and libc++ provided by macOS unless you know what you're doing.

llvm is keg-only, which means it was not symlinked into /usr/local,
because macOS already provides this software and installing another version in
parallel can cause all kinds of trouble.

If you need to have llvm first in your PATH, run:
  echo 'export PATH="/usr/local/opt/llvm/bin:$PATH"' >> /Users/runner/.bash_profile

For compilers to find llvm you may need to set:
  export LDFLAGS="-L/usr/local/opt/llvm/lib"
  export CPPFLAGS="-I/usr/local/opt/llvm/include"
==> Summary
🍺  /usr/local/Cellar/llvm/19.1.2: 8,0[41](https://github.com/python/cpython/actions/runs/11453246712/job/31865589688?pr=125499#step:6:42) files, 2GB
==> Caveats
==> llvm
LLD is now provided in a separate formula:
  brew install lld

We plan to build LLVM 20 with `LLVM_ENABLE_EH=OFF`. Please see:
  https://github.com/orgs/Homebrew/discussions/56[54](https://github.com/python/cpython/actions/runs/11453246712/job/31865589688?pr=125499#step:6:55)

To use the bundled libunwind please use the following LDFLAGS:
  LDFLAGS="-L/usr/local/opt/llvm/lib/unwind -lunwind"

To use the bundled libc++ please use the following LDFLAGS:
  LDFLAGS="-L/usr/local/opt/llvm/lib/c++ -L/usr/local/opt/llvm/lib/unwind -lunwind"

NOTE: You probably want to use the libunwind and libc++ provided by macOS unless you know what you're doing.

llvm is keg-only, which means it was not symlinked into /usr/local,
because macOS already provides this software and installing another version in
parallel can cause all kinds of trouble.

If you need to have llvm first in your PATH, run:
  echo 'export PATH="/usr/local/opt/llvm/bin:$PATH"' >> /Users/runner/.bash_profile

For compilers to find llvm you may need to set:
  export LDFLAGS="-L/usr/local/opt/llvm/lib"
  export CPPFLAGS="-I/usr/local/opt/llvm/include"
Error: Process completed with exit code 1.

What did you expect to happen?

To successfully install LLVM without error.

Step-by-step reproduction instructions (by running brew commands)

https://github.com/savannahostrowski/test_repo_python_install contains a minimum reproducer. The GHA essentially just runs setup-python and then installs various versions of Python with brew. You'll notice that 3.12 and 3.13 fail.

Run brew install [email protected]
  brew install [email protected]
  shell: /bin/bash -e {0}
  env:
    pythonLocation: /Users/runner/hostedtoolcache/Python/3.11.9/x64
==> Downloading https://ghcr.io/v2/homebrew/core/python/3.13/manifests/3.13.0_1
==> Fetching [email protected]
==> Downloading https://ghcr.io/v2/homebrew/core/python/3.13/blobs/sha256:d5257cc367cea5fb1003646077cdb644e8eb181045e2815255738242e05f8af2
==> Pouring [email protected]_1.ventura.bottle.tar.gz
Error: The `brew link` step did not complete successfully
The formula built, but is not symlinked into /usr/local
Could not symlink bin/idle3
Target /usr/local/bin/idle3
already exists. You may want to remove it:
  rm '/usr/local/bin/idle3'

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/idle3 -> /Library/Frameworks/Python.framework/Versions/3.12/bin/idle3
/usr/local/bin/pydoc3 -> /Library/Frameworks/Python.framework/Versions/3.12/bin/pydoc3
/usr/local/bin/python3 -> /Library/Frameworks/Python.framework/Versions/3.12/bin/python3
/usr/local/bin/python3-config -> /Library/Frameworks/Python.framework/Versions/3.12/bin/python3-config
/usr/local/share/man/man1/python3.1 -> /usr/local/Cellar/[email protected]/3.12.7/share/man/man1/python3.1
/usr/local/lib/pkgconfig/python3-embed.pc -> /usr/local/Cellar/[email protected]/3.12.7/lib/pkgconfig/python3-embed.pc
/usr/local/lib/pkgconfig/python3.pc -> /usr/local/Cellar/[email protected]/3.12.7/lib/pkgconfig/python3.pc
/usr/local/Frameworks/Python.framework/Headers -> /usr/local/Cellar/[email protected]/3.12.7/Frameworks/Python.framework/Headers
/usr/local/Frameworks/Python.framework/Python -> /usr/local/Cellar/[email protected]/3.12.7/Frameworks/Python.framework/Python
/usr/local/Frameworks/Python.framework/Resources -> /usr/local/Cellar/[email protected]/3.12.7/Frameworks/Python.framework/Resources
/usr/local/Frameworks/Python.framework/Versions/Current -> /usr/local/Cellar/[email protected]/3.12.7/Frameworks/Python.framework/Versions/Current
==> /usr/local/Cellar/[email protected]/3.13.0_1/bin/python3.13 -Im ensurepip
==> /usr/local/Cellar/[email protected]/3.13.0_1/bin/python3.13 -Im pip install -v --n
==> Caveats
Python is installed as
  /usr/local/bin/python3

Unversioned symlinks `python`, `python-config`, `pip` etc. pointing to
`python3`, `python3-config`, `pip3` etc., respectively, are installed into
  /usr/local/opt/[email protected]/libexec/bin

See: https://docs.brew.sh/Homebrew-and-Python
==> Summary
🍺  /usr/local/Cellar/[email protected]/3.13.0_1: 3,253 files, 63.2MB
Error: Process completed with exit code 1.

[Bo98]

This is a bug on GitHub's side: actions/runner-images#9966. They install python.org Python into the same place that Homebrew does which leads to the issues you've faced. I believe for backwards compatibility reasons, they're reluctant to change that decision now as even though the PATH is already configured correctly to not need to be installed in /usr/local/bin, someone might have a hardcoded reference to /usr/local/bin/python3 or something.

It's unfortunately not really fixable on our side. There's a number of possible solutions, depending on whichever suits your needs best:

• Use macos-14 or macos-15 which is unaffected by this bug, but you lose coverage for x86_64.
• Ask GitHub to update their pre-installed Homebrew Python to 3.13 (which doesn't fix it 100% of the time but does help for some people, and I suspect it will work for you given you only faced this issue recently): https://github.com/actions/runner-images/blob/4a0b4ab1fb88e3c87565bc645a2837593612d56f/images/macos/scripts/build/install-python.sh#L39.
• Run brew unlink python && brew link --overwrite python to fix the broken Python install. An alternative some use is find /usr/local/bin -lname '*/Library/Frameworks/Python.framework/*' -delete, depending on the order you install things. One of the two (or both together) should fix it for you.

At this point, the bug will eventually go away when macos-13 inevitably gets retired in about a year's time.

[savannahostrowski]

@Bo98 Ah, thanks for the context and the solutions. Super helpful!

It looks like find /usr/local/bin -lname '*/Library/Frameworks/Python.framework/*' -delete was the winner for our use case.

[carlocab]

Given how many people have run into this problem, I wonder if we should just overwrite these symlinks without erroring out in GitHub Actions (but show warning annotations so it's not missed).

Thoughts, @Homebrew/maintainers?

[MikeMcQuaid]

Given how many people have run into this problem, I wonder if we should just overwrite these symlinks without erroring out in GitHub Actions (but show warning annotations so it's not missed).

This makes sense to me 👍🏻