Installing PHP 8.x on macOS with Homebrew

macOS ships with an old system PHP that you should never use for development. This chapter walks you through installing and managing PHP 8.x using Homebrew — the standard approach used by professional PHP developers on Mac.

Why Not Use the System PHP?

macOS Ventura/Sonoma ships with PHP 8.x in /usr/bin/php, but it:

• Cannot be easily upgraded
• Lacks extensions like redis, imagick, xdebug
• Is not suitable for production-matching local development
• Has restricted php.ini you cannot reliably edit

Always use Homebrew PHP for local development.

Step 1: Install Homebrew

If you don't have Homebrew yet:

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

Verify it works:

brew --version
# Homebrew 4.x.x

Step 2: Add the shivammathur/php Tap

The official Homebrew php formula only keeps the latest stable PHP version. For access to PHP 8.0, 8.1, 8.2, and 8.3 simultaneously, you need the community tap by shivammathur:

brew tap shivammathur/php

This tap is the de-facto standard for multi-version PHP on macOS. It is actively maintained and tracks PHP releases within days.

Step 3: Install PHP 8.x

Install one or more versions:

# Install PHP 8.3 (latest stable as of 2025)
brew install shivammathur/php/php@8.3
# Install PHP 8.2 (LTS security support)
brew install shivammathur/php/php@8.2
# Install PHP 8.1 (for legacy project compatibility)
brew install shivammathur/php/php@8.1

Each version installs to its own prefix: - $(brew --prefix)/opt/php@8.3/bin/php - $(brew --prefix)/opt/php@8.2/bin/php

Step 4: Link the Active Version

After install, link the version you want as your default php command:

brew link --overwrite --force shivammathur/php/php@8.3

Verify:

php --version
# PHP 8.3.x (cli) (built: ...)

Step 5: Install Core Extensions

Most PHP work requires a set of standard extensions. Install them via Homebrew:

# For PHP 8.3
pecl install redis
pecl install xdebug
brew install imagemagick
pecl install imagick

Or use the shivammathur extension formula:

brew install shivammathur/extensions/xdebug@8.3
brew install shivammathur/extensions/redis@8.3

Step 6: Verify Your php.ini

Find and inspect your active php.ini:

php --ini
# Configuration File (php.ini) Path: /opt/homebrew/etc/php/8.3
# Loaded Configuration File: /opt/homebrew/etc/php/8.3/php.ini

Key settings to tune for local development (/opt/homebrew/etc/php/8.3/php.ini):

; Memory
memory_limit = 512M
; Error reporting (dev only)
error_reporting = E_ALL
display_errors = On
display_startup_errors = On
; Upload limits
upload_max_filesize = 100M
post_max_size = 100M
; Execution time
max_execution_time = 120

Verify Complete Installation

Run this diagnostic to confirm everything is working:

php -r "
echo 'PHP: ' . PHP_VERSION . PHP_EOL;
echo 'Extensions: ' . implode(', ', get_loaded_extensions()) . PHP_EOL;
echo 'INI: ' . php_ini_loaded_file() . PHP_EOL;
"

Directory Structure Summary

Apple Silicon (M1/M2/M3): Homebrew installs to /opt/homebrew. On Intel Macs it uses /usr/local. The $(brew --prefix) command always returns the correct path.

Next Step

Now that PHP 8.3 is installed, the next section shows how to switch seamlessly between PHP versions — essential when working across multiple projects with different version requirements.