Create a Joomla server on macOS using Homebrew

Setting up an Apache server with Homebrew on macOS Sequoia 15 remains one of the cleanest ways to build a local Joomla development environment in 2026. This guide walks you through installing Apache, PHP, and MariaDB via Homebrew, making the configuration adjustments needed, and getting Joomla running locally. Critically, this approach leaves the system version of Apache — which Apple has made increasingly awkward to work with — completely untouched. If you haven't yet installed Homebrew, do that first; it's the foundation everything else here builds on.

TL:DR – Installing Apache on macOS with Homebrew is straightforward: edit a few configuration files, set permissions, install PHP and MariaDB, then drop in Joomla. This is a local development setup, ideal for building and testing Joomla extensions and sites before pushing to a hosting provider. Production hosting on a Mac is not something I'd recommend — a managed host handles that far better.

What's changed in 2026

A few things are worth flagging before you dive in. PHP 8.4 is now the current stable release and is fully supported by Joomla 5.2 and later — that's what Homebrew will install by default, and it's what this guide uses throughout. MariaDB has moved on too; version 11.x is the current series available via Homebrew, replacing the older 10.x line. Joomla itself is now firmly in the 5.x era, with Joomla 4.x reaching end of life — if you're still running a 4.x test site locally, now is a good time to migrate.

Apple Silicon Macs (M1 through M4) are now the only hardware Apple ships, so this guide is written exclusively for ARM-based machines. Homebrew on Apple Silicon installs everything under /opt/homebrew rather than /usr/local. If you're somehow still on an Intel Mac, adjust those paths accordingly, but the steps are otherwise identical.

One other change worth noting: Apple quietly removed the built-in Apache start/stop shortcuts from recent versions of macOS, making the Homebrew-managed approach even more sensible than it already was. There's genuinely no good reason to wrestle with the system Apache in 2026.

Pre-requisites

Before installing anything, make sure your macOS environment is ready. The only hard dependency is Homebrew itself.

Homebrew

Check whether Homebrew is already installed by running brew --version in Terminal. A version number means you're good. If you see command not found, install Homebrew first — the official instructions at brew.sh involve pasting a single command into Terminal. You can also follow the guide on this site: Installing wget with Homebrew on macOS.

% brew --version
Homebrew 4.4.26

Once Homebrew is confirmed, update it before installing anything else:

% brew update
==> Updating Homebrew...
Already up-to-date.

You can also run brew doctor to catch any configuration issues. Warnings don't necessarily need action — read them, but don't panic.

% brew doctor
Please note that these warnings are just used to help the Homebrew maintainers
with debugging if you file an issue. If everything you use Homebrew for is
working fine: please don't worry or file an issue; just ignore this. Thanks!

Warning: Some installed formulae are deprecated or disabled.
You should find replacements for the following formulae:
  openssl@1.1

Installing Apache via Homebrew

With Homebrew ready, installing Apache is a single command:

% brew install httpd
...
==> Fetching httpd
==> Downloading
...
################################################################ 100.0%
==> Installing dependencies for httpd: ca-certificates
...
==> Installing httpd
==> Pouring httpd--2.4.63.arm64_sequoia.bottle.tar.gz
==> Caveats
DocumentRoot is /opt/homebrew/var/www.

The default ports have been set in /opt/homebrew/etc/httpd/httpd.conf to 8080 and in
/opt/homebrew/etc/httpd/extra/httpd-ssl.conf to 8443 so that httpd can run without sudo.

To start httpd now and restart at login:
  brew services start httpd
Or, if you don't want/need a background service you can just run:
  /opt/homebrew/opt/httpd/bin/httpd -D FOREGROUND

Verify the installation with httpd -v:

% httpd -v
Server version: Apache/2.4.63 (Unix)

Now start Apache as a background service so it launches automatically at login:

% brew services start httpd
==> Successfully started `httpd` (label: homebrew.mxcl.httpd)

If Apache is already running from a previous install, restart it instead: brew services restart httpd.

By default, Homebrew configures Apache to listen on port 8080 rather than 80, avoiding conflicts with anything else macOS might have running. Visit http://localhost:8080 in your browser — you should see the classic Apache "It works!" page.

Configuring Apache

Apache's configuration lives at /opt/homebrew/etc/httpd/httpd.conf. Open it with your editor of choice — vi, nano, VS Code, whatever you prefer:

sudo vi /opt/homebrew/etc/httpd/httpd.conf

Document Root

The default document root is /opt/homebrew/var/www. This is a sensible location — it sits well away from macOS system directories and is fully writable by your user account. You can add virtual hosts later if you need to run multiple sites simultaneously, but for a single Joomla dev environment this default works perfectly.

% ls /opt/homebrew/var/www
cgi-bin    index.html
% cat /opt/homebrew/var/www/index.html
<html><body><h1>It works!</h1></body></html>

Skipping user directories

The macOS built-in Apache has a concept of user directories tied to the ~/Sites folder. With Homebrew managing our own separate Apache instance, there's no reason to touch any of that. Keep it simple — use the Homebrew document root and leave user directories alone.

Sanity-check the configuration

After any edit to httpd.conf, run a syntax check before restarting:

% apachectl configtest
AH00557: httpd: apr_sockaddr_info_get() failed for mac
AH00558: httpd: Could not reliably determine the server's fully qualified domain name, using 127.0.0.1. Set the 'ServerName' directive globally to suppress this message
Syntax OK

The warnings about ServerName are harmless on a local dev machine. Syntax OK is what matters.

Enabling PHP in Apache for Joomla

Installing PHP via Homebrew

Joomla requires PHP. Install the current stable release with:

% brew install php

This installs PHP 8.4, which is the current stable version and is fully supported by Joomla 5.2 and later. Confirm it installed correctly:

% php -v
PHP 8.4.5 (cli) (built: Mar 12 2025 01:55:56) (NTS)
Copyright (c) The PHP Group
Built by Homebrew
Zend Engine v4.4.5, Copyright (c) Zend Technologies
    with Zend OPcache v8.4.5, Copyright (c), by Zend Technologies

If you need to test against multiple PHP versions — say, PHP 8.3 alongside 8.4 — Homebrew supports parallel installs via brew install php@8.3 and switching between them. For most Joomla development a single version is all you need.

Enabling PHP in the Apache configuration

Open /opt/homebrew/etc/httpd/httpd.conf again and find this line:

#LoadModule rewrite_module lib/httpd/modules/mod_rewrite.so

Remove the leading # to enable mod_rewrite, which Joomla uses for clean URLs. Directly below it, add the PHP module line:

LoadModule rewrite_module lib/httpd/modules/mod_rewrite.so
LoadModule php_module /opt/homebrew/opt/php@8.4/lib/httpd/modules/libphp.so

Configuring Apache to serve PHP files

Without the following changes, Apache will serve PHP files as raw source code rather than executing them. Find the DirectoryIndex block and update it:

Before (HTML only):

<IfModule dir_module>
    DirectoryIndex index.html
</IfModule>

After (PHP and HTML):

<IfModule dir_module>
    DirectoryIndex index.php index.html
</IfModule>

Then add a FilesMatch directive so Apache hands .php files to the PHP handler:

<FilesMatch \.php$>
    SetHandler application/x-httpd-php
</FilesMatch>

Test PHP is working

Create a file called info.php in your document root with this single line:

<?php phpinfo();

Stop and restart Apache:

% brew services stop httpd
Stopping `httpd`... (might take a while)
==> Successfully stopped `httpd` (label: homebrew.mxcl.httpd)

% brew services start httpd
==> Successfully started `httpd` (label: homebrew.mxcl.httpd)

Load http://localhost:8080/info.php — you should see the full PHP info page, confirming PHP 8.4 is active and was built by Homebrew.

Installing a MySQL-compatible database with Homebrew

Joomla supports both MySQL and MariaDB. MariaDB is the better choice for local development — it's fully Joomla-compatible, actively maintained, and the version available via Homebrew (currently the 11.x series) is more permissively licensed than MySQL's newer releases.

Install MariaDB

% brew install mariadb
...
==> Fetching mariadb
...
==> Installing mariadb
...
A "/etc/my.cnf" from another install may interfere with a Homebrew-built
server starting up correctly.

MySQL is configured to only allow connections from localhost by default

To start mariadb now and restart at login:
  brew services start mariadb
Or, if you don't want/need a background service you can just run:
  /opt/homebrew/opt/mariadb/bin/mariadbd-safe --datadir\=/opt/homebrew/var/mysql

Start MariaDB

% mysql.server start
Starting MariaDB
/opt/homebrew/Cellar/mariadb/11.7.2/bin/mysqld_safe: Deprecated program name. It will be removed in a future release, use 'mariadbd-safe' instead
250328 13:43:03 mysqld_safe Logging to '/opt/homebrew/var/mysql/mac.err'.
250328 13:43:03 mysqld_safe Starting mariadbd daemon with databases from /opt/homebrew/var/mysql
.. SUCCESS!
% brew services start mariadb
==> Successfully started `mariadb` (label: homebrew.mxcl.mariadb)

Sign in and set a root password

Log in as root using sudo mysql -u root, then set a password — Joomla's installer requires one:

% sudo mysql -u root
Password:
Welcome to the MariaDB monitor.  Commands end with ; or \g.
Your MariaDB connection id is 13
Server version: 11.7.2-MariaDB Homebrew

Copyright (c) 2000, 2018, Oracle, MariaDB Corporation Ab and others.

Type 'help;' or '\h' for help. Type '\c' to clear the current input statement.

MariaDB [(none)]> ALTER USER 'root'@'localhost' IDENTIFIED BY 'yournewpassword';
Query OK, 0 rows affected (0.012 sec)

MariaDB [(none)]> FLUSH PRIVILEGES;
Query OK, 0 rows affected (0.002 sec)

MariaDB [(none)]>

Installing Joomla 5

Download the latest Joomla 5 full package from downloads.joomla.org. Unzip it into your document root at /opt/homebrew/var/www, then open http://localhost:8080/index.php in your browser to start the installer.

Joomla Installer — Site configuration

Set your preferred language, give the site a name, and move on. On a Mac you can use your machine's Bonjour name (ending in .local) as the site name if you want to avoid configuring DNS locally.

Joomla Installer — Login data

Enter the super user credentials you'll use to log into the Joomla administrator: real name, username, a strong password, and email address.