Install PHP (with extensions) on MacOS using Homebrew


This article has detailed steps on doing clean install of PHP 7.2 (latest PHP version as of August 2018). If you already have PHP installed via homebrew, then it requires you to first remove those PHP installations and then do the fresh PHP install. Reason of doing so, is to avoid conflicts that arise because of Homebrew March 2018 updates. Further details within blog!

Problem Background

Recently, I wanted to include a new module (visualception) in my test automation project that is built on top of codeception. In order to successfully make it work, there was a requirement to have php-imagick extension already installed in your system.

Initial search showed that, in past you could have installed php-imagick extension using command like brew install php71-imagick, but this does not work any more of Homebrew updates. With the migration to Homebrew-core, the php formula has stopped taking over the role of PECL. So now for installation of php extensions (like imagick or x-debug) you have to use PECL.

Due to older php installations, I was getting lot of issues while trying to install php-imagick extension. Ultimately, I was able to resolve all the problems by installing PHP from scratch. In below, I have listed all the steps for fresh PHP installation.

1. Prerequisite Steps For First Time PHP-Installation

In order to install PHP via Homebrew, we first need to install xcode-command-line tools and Homebrew. If these tools are already setup in your machine, then skip to next section.

1.1 First install xcode-command-line tools by running below command in terminal. If any popup message appears during installation, that needs to be confirmed. For further details on xcode tools, you may check this link.

xcode-select --install

1.2 As we are going to do all PHP related installations through macOS package manager Homebrew. So next we need to set it up by running below command:

/usr/bin/ruby -e "$(curl -fsSL"

Installation process will will show several prompts and may also ask for mac password. This may take a few minutes. Once it is done, you can verify the installation was successful by running below commands:

brew --version # it will return the Homebrew installed version number like .. Homebrew 1.7.2

brew doctor # it will ensure everything is configured correctly and if something is wrong then give instructions to fix


If you already have any PHP-related installations (php71 or older) done by homebrew then it is best to remove and clean all those installations. For me, they gave lot of conflicts and errors. Removing all of existing PHP-related installations and installing fresh was much more simpler. In case you donot have any existing php-homebrew installations OR want to keep them, then skip to next section.

2.1 Removing all PHP-Homebrew related installations

First run below brew commands to make sure brew is updated and has no configuration issues.

brew update  # updates brew itself
brew upgrade # upgrades all packages installed via brew
brew cleanup # by default, brew doesnot uninstall old versions. cleanup command will do the job
brew doctor  # Checks brew state and returns error, if there are any issues

If brew doctor or cleanup throws any errors then fix them as per instructions returned by brew-doctor or ask google šŸ™‚

Now onto removing existing PHP-related installations (that were done by homebrew).

brew list | grep php # will show list of existing php installations done via homebrew
brew uninstall --force $x # where $x = value returned by above command (brew list | grep php)
rm -rf /usr/local/Cellar/php  # run to ensure php dir removed
rm ~/Library/LaunchAgents/homebrew.mxcl.php* # run to remove launch agents
sudo rm /Library/LaunchDaemons/homebrew.mxcl.php*

ps ax | grep php # checks php processes, if any still running then reboot

After above, again run brew cleanup and brew doctorĀ  to ensure everything working fine.


3.1 Run PHP Installation commands

brew install php # this command will install latest available version of php

Or if you want to install specific versions you may run commands like below

brew install php@5.6 # these are version specific commands. run these if specific version required.
brew install php@7.0 
brew install php@7.1
brew install php@7.2

hash -r # update bash's internal paths

Once done with above, now verify thatyou are running the correctĀ homebrewPHP by running type php command. If it returnsĀ /usr/local/...anything.../php then it means you areĀ  running homebrew-PHP. If it returns something likeĀ /usr/bin/php then it means you are running apple-supplied-PHP. In that case you need to fix paths, as we want to use homebrew-PHP! Finally run brew doctor to make sure everything is fine and no configuration errors are thrown.

3.2 Switching between PHP versions

If you have multiple php versions and want to switch between them, then you can do so by using brew link and brew unlink commands.

# Running below commands will switch php5.6 from php7.2
brew unlink php@7.2
brew link --force --overwrite php@5.6
brew doctor # to ensure all configs are fine
php -v # verify successful relinking done

# To again switch to php7.2 from php5.6 do below commands 
brew unlink php@5.6
brew link --force --overwrite php@7.2
brew doctor # to ensure all configs are fine
php -v # to verify successful relinking done

3.3 Install PHP extensions

As mentioned in start, php extensions such as php-imagick or php-xdebug which were previously installed by commands like (brew install php53-imagick) now should be installed by PECL (for details on PECL check this link). Below are example commands for installation of xdebug and imagick extension.

pecl install xdebug
pecl install imagick

Now you may run php -v to verify php version and php -m to check enabled extensions.


Arif Masood

Software Quality Professional. Perfectionist. Love to explore new tools, technologlies & processes. Worked on several web & mobile projects in last 7+ years. Mostly in areas of Functional, API, Automation & Performance testing. Ocassional blogger - trying to be more regular one :)