macOS runner: Homebrew "brew link" symlink conflict in CI

Homebrew tried to symlink a formula into the prefix but a file at the target path already exists. The link step fails and the formula stays "keg-only" or unlinked until the conflict is resolved.

What this error means

A brew step prints "Error: Could not symlink <path>. Target <path> already exists. You may want to remove it" and the tool is not on PATH afterward.

Error: Could not symlink bin/python3.12
Target /usr/local/bin/python3.12 already exists. You may want to remove it:
  rm '/usr/local/bin/python3.12'

To force the link and overwrite all conflicting files:
  brew link --overwrite python@3.12

Common causes

A pre-existing file occupies the link target

Another formula, the image, or a manual copy already placed a file at the path Homebrew wants to symlink, so it refuses to overwrite by default.

Two formulae provide the same executable name

Conflicting kegs (for example two python versions) both want python3 in the prefix bin, and only one can own the link.

How to fix it

Force the link with --overwrite

When you know the conflicting file is safe to replace, let Homebrew overwrite the existing symlinks.

brew link --overwrite python@3.12

Remove the stale file then relink

1. Read the exact target path printed in the error.
2. Remove the conflicting file Homebrew named.
3. Re-run brew link <formula> so the symlink is created cleanly.

rm '/usr/local/bin/python3.12'
brew link python@3.12

How to prevent it

• Avoid installing two formulae that own the same executable name.
• Use brew link --overwrite deliberately when a conflict is expected.
• Reference tools by full keg path when both versions must coexist.

Related guides