Switch PHP Versions on a Mac with Homebrew

To switch PHP versions on a Mac, install the version you want with Homebrew, then unlink the active PHP with brew unlink and relink the one you want with brew link --overwrite --force. Installing alone does not change what php -v reports.

That single point is where almost everyone gets stuck. If you ran brew install php@8.3 and the version still has not changed, the problem is linking and PATH, not the install.

This article covers installing, switching, and how to diagnose it when the change does not take effect.

Installing PHP with Homebrew

The short answer: Homebrew can hold several PHP versions at once, so install everything you might need up front.

Install Homebrew first

If you do not have it, run the official installation command.

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

brew -v printing a version means it worked. The wider setup is covered in installing Homebrew and Vim on a Mac.

Check which versions are available

The short answer: wrap the search in a regular expression so only the php@ formulae come back.

brew search '/^php(@[0-9.]+)?$/'

As of September 2026, homebrew-core carries these five.

Versions are removed as they go out of support. For something older, such as the 7 series, use the tap described at the end.

Install the version you want

brew install php@8.3

For the latest release, brew install php is enough. Even after this finishes, php -v still reports the old version. The next section is the actual work.

Switching the active PHP version

The short answer: two steps. Unlink the current one, then link the one you want.

Check what is running now

php -v

Unlink, then link again

The short answer: this is the core of the switch.

# drop the link for the currently active PHP
brew unlink php

# link the version you want
brew link --overwrite --force php@8.3

Versioned formulae such as php@8.1 are keg-only, meaning installing them does not put them on your PATH. That is why --force is required. --overwrite replaces the existing symlinks rather than failing on them.

Set the PATH and reopen the terminal

If linking alone does not do it, put the path in your shell config. For zsh that is ~/.zshrc.

export PATH="/opt/homebrew/opt/php@8.3/bin:$PATH"
export PATH="/opt/homebrew/opt/php@8.3/sbin:$PATH"

On an Intel Mac read /usr/local in place of /opt/homebrew. Then reload.

source ~/.zshrc
php -v

If the version you chose appears, the switch is done. For editing shell config and tidying the terminal generally, see setting up the Mac terminal with Iceberg and Prezto pure.

Why has php -v not changed?

The short answer: usually another PHP sits earlier on your PATH than Homebrew’s.

List every php on the PATH

The short answer: which -a php prints every php on the PATH in priority order, and the first line is the one that runs.

which -a php
type -a php

type -a also picks up aliases and shell functions, so check both. If the first line is anything other than /opt/homebrew/bin/php, that path is ahead of Homebrew’s.

The usual culprits:

• A manual or system install at /usr/local/php/bin
• A path added by MAMP or XAMPP
• /usr/local/bin sitting before /opt/homebrew/bin on an Apple Silicon machine

Open ~/.zshrc and check that Homebrew’s path is not written after those.

Stale symlinks

If brew link reports “Target already exists”, an old symlink is in the way. Remove it and link again.

ls -la /opt/homebrew/bin/php*
rm /opt/homebrew/bin/php
brew link --overwrite --force php@8.3

Check which php.ini is loaded

If the version switched but extension behaviour did not, the config file from the previous version may still be in use.

php -i | grep "Loaded Configuration"

Confirm the path points into the directory for the version you switched to. If you run php-fpm, restart the service too.

brew services restart php@8.3

Getting a version that homebrew-core no longer carries

The short answer: use the shivammathur/php tap, which holds each release from PHP 5.6 onward.

brew tap shivammathur/php
brew install shivammathur/php/php@7.4
brew unlink php
brew link --overwrite --force shivammathur/php/php@7.4

PHP versions past end of life do not receive security fixes. Use them only where maintaining an old project requires it, and keep them out of production.

Three commands are all you need

The short answer: brew install, brew unlink and brew link --overwrite --force. When it still will not change, look at PATH with which -a php.

1. brew install php@8.3 to install
2. brew unlink php to drop the current link
3. brew link --overwrite --force php@8.3 to relink
4. source ~/.zshrc then php -v to confirm
5. If unchanged, run which -a php and look at the first line