Homebrew PHP appears not to be linked. - Valet
Stefan Bogdanescu
Founder & Senior Architect · 2026-06-29
# Homebrew PHP Appears Not to Be Linked: A Developer's Guide to Fixing Valet Environment Errors
As developers building local environments, we often encounter frustrating dependency issues. One specific error that plagues many users trying to set up local servers like Valet, especially on macOS using Homebrew, is the cryptic message: `Homebrew PHP appears not to be linked.` This usually halts the setup process and causes confusion about why the environment isn't recognized.
This post will dive deep into the root cause of this problem and provide a comprehensive, step-by-step solution, ensuring your local development stack is properly configured for success.
## Understanding the Linkage Problem
The error message indicates that while Homebrew successfully installed PHP, the necessary symbolic links or environment variables required by tools like Valet (which relies on specific paths to execute PHP commands) are either missing or broken.
When you install software via Homebrew, it places files in specific directories. For these tools to "see" and use that installation, those files must be correctly linked into the system's executable path (`$PATH`). If this linking process fails, Valet cannot locate the PHP binary, leading to the error. This is a classic dependency management issue, similar to ensuring correct package dependencies when managing frameworks like those found on [laravelcompany.com](https://laravelcompany.com).
## The Solution: Re-linking and Environment Verification
The fix almost always involves explicitly forcing Homebrew to re-link or verify its installation paths. Follow these steps sequentially to resolve the linkage issue:
### Step 1: Ensure PHP is Installed Correctly
First, confirm that your desired PHP version (e.g., `php7.1` in your case) is properly installed via Homebrew.
```bash
# Check if php7.1 is installed
brew list | grep php
# If not installed, install it:
brew install php@7.1
```
### Step 2: Re-link the Installation
If PHP is installed but not linked correctly for system access, running the `brew link` command is essential. This command creates the necessary symbolic links that allow other programs to find the binaries.
Execute the following command to ensure the installation is properly linked:
```bash
brew link php@7.1 --force
```
The `--force` flag helps overwrite any potentially broken or incomplete links, forcing Homebrew to rebuild the necessary environment pointers.
### Step 3: Verify the PATH Environment Variable
Even after linking, sometimes the shell session needs a refresh. Ensure that Homebrew's binaries are correctly included in your system's `$PATH`. Check your shell configuration file (e.g., `~/.zshrc` or `~/.bash_profile`) to confirm that the Homebrew binary directories are present.
You can verify the current path settings:
```bash
echo $PATH
```
If you suspect environment issues, a clean restart of your terminal session is often the quickest way to ensure new environment variables are loaded correctly.
### Step 4: Reinstall Valet Dependencies
After successfully linking PHP, attempt the Valet installation command again. This time, Valet should be able to resolve the location of the linked PHP executable without throwing the linkage error.
```bash
valet install
```
## Conclusion
The "Homebrew PHP appears not to be linked" error is rarely a fatal flaw in the PHP installation itself; rather, it’s an issue with how the package manager (Homebrew) has integrated that software into the operating system's execution environment. By systematically re-linking the specific PHP version and verifying your `$PATH` configuration, you resolve this linkage problem. Mastering these fundamental environment steps is crucial for any senior developer aiming to build robust, predictable local development environments, whether you are working with complex frameworks or standard web applications like those found in the Laravel ecosystem.