Homebrew’s link and unlink commands are your primary tools for managing what gets added to your system’s PATH, and how different Homebrew-installed versions of software coexist.
Let’s see this in action. Suppose you’ve installed imagemagick and ghostscript. Both might install executables with the same name, like convert. Homebrew, by default, will link the executables from the latest installed package into /usr/local/bin (or /opt/homebrew/bin on Apple Silicon).
$ brew list imagemagick
/usr/local/Cellar/imagemagick/7.1.0-55/bin/convert
# ... other files
$ brew list ghostscript
/usr/local/Cellar/ghostscript/9.56.1/bin/convert
# ... other files
$ ls -l /usr/local/bin/convert
lrwxr-xr-x 1 user admin 38 Feb 15 10:00 /usr/local/bin/convert -> ../Cellar/imagemagick/7.1.0-55/bin/convert
Here, convert from imagemagick is linked, meaning it’s the one that will run when you type convert in your terminal. If you wanted to use the convert from ghostscript instead, you’d need to intervene.
The core problem Homebrew’s linking mechanism solves is preventing the "dependency hell" where multiple packages try to install files into the same system locations, especially executables in bin directories. Homebrew handles this by installing packages into their own versioned directories within the "Cellar" (/usr/local/Cellar/ or /opt/homebrew/Cellar/) and then creating symbolic links from a central location (like /usr/local/bin/) to the active version’s executables.
When you install a package, Homebrew automatically links its executables. If a conflict arises (meaning a file already exists in the target linking directory), Homebrew will usually complain and refuse to link. You can then manually unlink the conflicting package’s files or the new package’s files.
Let’s say you want to use the convert command from ghostscript instead of imagemagick.
First, you’d unlink the convert executable from imagemagick:
$ brew unlink imagemagick
Unlinking /usr/local/Cellar/imagemagick/7.1.0-55/bin/convert...
Unlinking /usr/local/Cellar/imagemagick/7.1.0-55/share/man/man1/convert.1.gz...
# ... other unlinked files
Now, if you try to link ghostscript, Homebrew will link its convert executable:
$ brew link ghostscript
Linking /usr/local/Cellar/ghostscript/9.56.1/bin/gs...
Linking /usr/local/Cellar/ghostscript/9.56.1/bin/gs-9.56.1...
Linking /usr/local/Cellar/ghostscript/9.56.1/share/ghostscript/9.56.1/Resource/Font/NimbusMonL-Regu...
# ... other linked files
# Check which convert is now linked
$ ls -l /usr/local/bin/convert
lrwxr-xr-x 1 user admin 39 Feb 15 10:05 /usr/local/bin/convert -> ../Cellar/ghostscript/9.56.1/bin/convert
Now, typing convert will execute the version from ghostscript. To switch back, you’d unlink ghostscript and then brew link imagemagick.
You can also unlink specific files if you don’t want to unlink the entire package, though this is less common. For example, if you only wanted to remove the convert executable from the imagemagick link:
$ brew unlink --force --overwrite imagemagick/bin/convert
The --force option tells Homebrew to unlink even if it’s not the primary link, and --overwrite is often needed when Homebrew detects the file might have been manually modified or linked elsewhere.
The power here is granular control. If you have multiple versions of Python installed, for example, and pip or python executables clash, you can selectively link or unlink specific binaries to ensure your PATH points to the desired version. It’s also crucial when a new version of a package you rely on installs a conflicting executable – you can keep the old version linked by unlinking the new one, or vice-versa.
A common pitfall is forgetting that Homebrew’s linking is relative to its bin directory (e.g., /usr/local/bin). If you have other directories in your PATH that contain executables with the same name, those will be checked before Homebrew’s linked executables, potentially leading to confusion about which version is actually running.
The next concept you’ll likely encounter is managing Homebrew’s own PATH configuration, especially when dealing with multiple Homebrew installations or non-standard installation prefixes.