When brew link stops because a path already exists, first identify what owns that path. If it is a symlink from another Homebrew formula, unlink that formula; if it is an unrelated file, inspect Homebrew’s dry run before considering overwrite. A conflict does not mean the new formula failed to install: it may already be present in its keg, awaiting a safe link into Homebrew’s shared prefix. Homebrew’s brew manual
What the conflict message tells you
A Homebrew formula is installed in a versioned keg, and brew link creates symlinks into shared directories such as bin, lib, and include. The error usually names a target path and may say it belongs to another formula or that it already exists. Homebrew documents brew link as linking installed files into its prefix, while brew unlink removes a formula’s links from that prefix. Homebrew brew manual
The safe next step depends on ownership. Replacing a Homebrew symlink can switch which formula supplies a command or library. Replacing an unrelated file can affect software outside Homebrew. Read the full error and do not treat --overwrite as a generic repair switch.
Inspect the formula and the colliding path
Use the formula name shown in the failed link command in place of FORMULA. brew info can show formula details, including whether it is keg-only; brew list summarizes files in the current keg. You can also ask for its active prefix without hard-coding a Mac’s Intel or Apple silicon Homebrew location:
brew info FORMULA
brew list FORMULA
brew --prefix FORMULA
If the error says the existing target is a symlink belonging to another formula, note that formula’s name too. The conflict message may provide a direct brew unlink OTHER_FORMULA suggestion. If the target is an ordinary file, a link from a cask, or something whose owner is unclear, pause and investigate before changing it. Do not delete it just because Homebrew reports a collision.
Resolve a conflict owned by another formula
When the target belongs to a different formula and you want the new formula to provide the conflicting path, unlink the old formula, then link the requested one:
brew unlink OTHER_FORMULA
brew link FORMULA
Unlinking removes that formula’s symlinks from the prefix; it does not uninstall its keg. The old formula can be linked again later if needed. Homebrew also documents unlinking and relinking as a way to temporarily disable a formula. Homebrew brew manual
If the other formula is still needed, remember that unlinking it can make its commands or files unavailable through the shared prefix. Avoid unlinking several packages speculatively. For a conflict that is not clearly another formula’s symlink, continue with a dry run and inspect each listed path.
Preview before using --overwrite
Homebrew’s --overwrite option deletes files already in its prefix while linking. Its --dry-run option lists files that would be linked or deleted without changing them. Preview the requested operation first:
brew link --overwrite --dry-run FORMULA
Review the paths carefully. If the list includes files you recognize as needed by another tool, or anything outside the expected Homebrew prefix, do not proceed until you understand its owner and purpose. If the preview contains only files you intend to replace, run the actual command:
brew link --overwrite FORMULA
This changes paths in the shared prefix. The preview is the decision point; it does not itself resolve the conflict. Homebrew brew manual
If the formula is keg-only
A separate message may say the formula is keg-only and must be linked with --force. Keg-only means Homebrew keeps the formula in its own keg instead of linking it into the common prefix. Homebrew uses that arrangement to avoid shadowing macOS software or conflicting with another formula. Check brew info FORMULA for the reason and any usage guidance. Homebrew FAQ
Do not add --force just because a normal link reports a path conflict: --force permits linking a keg-only formula; it does not mean the conflicting paths are safe to overwrite. Homebrew advises against force-linking keg-only dependencies globally, since unrelated builds and system commands can then resolve a different dependency. For a build that needs a keg-only tool or library, Homebrew recommends using its formula prefix for that build rather than exposing it globally. Homebrew’s keg-only dependency guide
Confirm the result and know when to stop
After resolving the specific conflict, check the formula’s link state and retry only if necessary:
brew list --versions FORMULA
brew link FORMULA
If it is already linked, Homebrew may report that rather than creating links again. If linking still fails, use the new error to identify the remaining path; do not repeat overwrite blindly. When the target is not clearly Homebrew-managed, or the dry run shows files you cannot safely replace, leave the link unresolved and investigate the owning software first. The keg remains a distinct installation from its links in the prefix, so an installed formula can remain available for diagnosis even while linking is incomplete.