The simplest Docker setup for local WordPress development is one Compose file with three pieces: the official WordPress image, a pinned MariaDB image and a WP-CLI container, with only your plugin or theme folder mounted from your computer. If you would rather not write that file, npx @wordpress/env start builds a similar environment for you. Both routes need Docker running. If Docker is not already part of your work, Local, WordPress Studio or Playground get you to a working site faster, and we say when each one is the better pick below.
We checked everything on 15 November 2026. Image tags and dates come from Docker Hub, release pages and vendor documentation. We ran the Compose file in this guide on Docker 29.9.2 and Compose 5.6.1 on an Apple silicon Mac: it started WordPress 7.1.4 on PHP 8.3.36 with MariaDB 11.8.9, WP-CLI installed the site, and we built the Xdebug image with Xdebug 3.5.3. Everything was removed afterwards. We did not run wp-env, DDEV or Lando in this pass, so what we say about them is taken from their own documentation and is marked that way.
Is Docker the right way to run WordPress locally?
Docker is the right choice when you need the same PHP and database versions as production, run several projects side by side, want the environment defined in a file that lives in the repository, or run the same setup in CI. It is more than you need if you only want a site to click around in. Containers add a layer to learn (volumes, ports, user IDs), and on macOS and Windows they run inside a virtual machine, so file access is slower than a native tool.
Option | Best for | Needs Docker | Status checked 15 Nov 2026 |
|---|---|---|---|
Docker Compose, your own file | Full control, same file in CI and for teammates | Yes | Official images rebuilt on 12 Nov 2026 |
wp-env | Plugin and theme work, PHPUnit and end-to-end tests | Yes by default; Playground and PHP runtimes also exist | @wordpress/env 12.1.0, needs Node 22.13 or newer |
DDEV | Many projects, local HTTPS names, shared team config | Yes (needs a Docker provider) | Release v1.25.5, 26 Oct 2026 |
Lando | Per-project config file with a WordPress recipe | Yes | Release v3.26.9, 20 Aug 2026 |
Local | Click-to-create sites, no terminal | No | Free download from WP Engine |
WordPress Studio | Desktop app and CLI from Automattic | No (requirements list only the operating system) | Release v2.2.0, 11 Nov 2026 |
WordPress Playground | Throwaway sites, demos, quick tests | No | Documentation at developer.wordpress.org/playground |
A fair rule: pick the lightest tool that matches production closely enough for the bug or feature in front of you. A layout fix rarely needs a container. A plugin that reads $wpdb and runs on MariaDB in production deserves the real database engine locally.
Which Docker images should you use for WordPress?
Use the official wordpress image with an explicit tag, and pin the database too. On 15 November 2026 the latest tag is WordPress 7.1.4 on PHP 8.3 with Apache. Tags also exist for PHP 8.2, 8.4 and 8.5, and for the fpm and fpm-alpine variants if you want to put your own web server in front.
What | Tag to use | What it is on 15 Nov 2026 |
|---|---|---|
WordPress, Apache |
| WordPress 7.1.4, PHP 8.3 (same image as |
WordPress, newer PHP |
| Same release on PHP 8.5; |
WP-CLI |
| WP-CLI 2.12.0 on Alpine, tags for PHP 8.2 to 8.5 |
MariaDB, pinned |
| 11.8.9, long-term support until 13 Feb 2030 |
MySQL, alternative |
| 8.4.13, published 3 Nov 2026 |
Why pin mariadb:11.8 and not lts? The lts tag currently points at MariaDB 12.3.3, and it will move again when MariaDB names a new long-term release. A moving tag can upgrade your database engine without you noticing, and going back is hard: MariaDB will not start on a data directory last used by a newer version, as the wp-env README warns. Pin the major version for any project that lives for months. WordPress.org recommends MariaDB 10.11 or newer, or MySQL 8.4 or newer, and PHP 8.3 or newer. Our guide to PHP 8.3 features for WordPress developers covers what that version changes for your code.
PHP 8.6 is not in the image yet. The maintainers have an open request (docker-library/wordpress issue 1027, opened 4 Nov 2026) to add PHP 8.6 images for testing ahead of WordPress 7.2. If you need to test against it today, see our PHP 8.6 guide for plugin authors and build from the PHP image yourself.
How do you set up WordPress with Docker Compose?
Create an empty project folder, put your plugin in plugins/my-plugin, and save this as compose.yaml. It runs three services: db, wordpress and a wpcli container that only starts when you ask for it. Checked on 15 Nov 2026 with docker compose config and a full start on Docker 29.9.2.
name: wpdev
x-wp-env: &wp-env
WORDPRESS_DB_HOST: db
WORDPRESS_DB_NAME: wordpress
WORDPRESS_DB_USER: wp
WORDPRESS_DB_PASSWORD: wp-dev-only
WORDPRESS_DEBUG: "1"
WORDPRESS_CONFIG_EXTRA: |
define( 'WP_ENVIRONMENT_TYPE', 'local' );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false );
services:
db:
image: mariadb:11.8
restart: unless-stopped
environment:
MARIADB_DATABASE: wordpress
MARIADB_USER: wp
MARIADB_PASSWORD: wp-dev-only
MARIADB_RANDOM_ROOT_PASSWORD: "1"
volumes:
- db_data:/var/lib/mysql
healthcheck:
test: ["CMD", "healthcheck.sh", "--connect", "--innodb_initialized"]
interval: 5s
timeout: 5s
retries: 20
wordpress:
image: wordpress:7.1.4-php8.3-apache
restart: unless-stopped
depends_on:
db:
condition: service_healthy
ports:
- "${WP_PORT:-8080}:80"
environment: *wp-env
volumes:
- wp_data:/var/www/html
# Mount only the code you are working on, not the whole WordPress tree.
- ./plugins/my-plugin:/var/www/html/wp-content/plugins/my-plugin
wpcli:
image: wordpress:cli-php8.3
profiles: ["tools"]
# The CLI image is Alpine (www-data = uid 82); the Apache image is Debian (uid 33).
user: "33:33"
depends_on:
db:
condition: service_healthy
environment: *wp-env
volumes:
- wp_data:/var/www/html
- ./plugins/my-plugin:/var/www/html/wp-content/plugins/my-plugin
mailpit:
image: axllent/mailpit:v1.33.1
profiles: ["mail"]
ports:
- "8025:8025" # web inbox
- "1025:1025" # SMTP
volumes:
db_data:
wp_data:The parts that matter, in the order you will bump into them:
- Healthcheck and
depends_on. The MariaDB image ships ahealthcheck.shscript but no default health check, so we add one. WordPress waits until the database reports healthy, which avoids the first-start “Error establishing a database connection” page. Docker documents this pattern in its startup order guide. - Two named volumes.
db_datakeeps your database across restarts.wp_dataholds WordPress core, uploads andwp-config.phpinside Docker’s own storage, which is much faster on macOS and Windows than a folder on your disk. - One bind mount. Only
plugins/my-plugincomes from your computer, so your editor and the container see the same files. Swap it for a theme path if that is what you build. - Shared environment block. The
x-wp-envanchor feeds the same settings to both WordPress and WP-CLI. This matters: the image readsWORDPRESS_CONFIG_EXTRAevery time PHP starts, not once. When we left it off the CLI container,wp evalreported the environment type asproductionwhile the browser sawlocal. After sharing the block, both saidlocal. - Credentials. The password in the file is for a database nobody can reach from outside the Compose network. Do not reuse it anywhere real.
Start it and install the site:
docker compose up -d
docker compose --profile tools run --rm wpcli wp core install \
--url=http://localhost:8080 --title="Dev site" \
--admin_user=admin --admin_password=admin \
--admin_email=dev@example.com --skip-email
docker compose --profile tools run --rm wpcli wp plugin activate my-pluginOpen http://localhost:8080. If port 8080 is taken, run WP_PORT=8090 docker compose up -d; the file reads that variable. Our run showed WordPress 7.1.4 from wp core version and the plugin listed as inactive until activated, which is the expected state for a fresh mount.
How do you run WP-CLI in a Docker setup?
Run it as a one-off container that shares the WordPress volume: docker compose --profile tools run --rm wpcli wp <command>. The --rm flag deletes the container when the command ends, and the tools profile keeps it out of docker compose up. If typing that gets old, add a shell alias:
alias wpd='docker compose --profile tools run --rm wpcli wp'
wpd option get siteurl
wpd plugin list --fields=name,status
wpd db export - | gzip > backup.sql.gzThe file sets user: "33:33" on the CLI service for a reason, covered in the permissions section below. Without it, commands that write files fail. For the commands worth learning first, and a way to keep an AI agent read-only while it uses them, see our WP-CLI guide.
How do you debug PHP with Xdebug in Docker?
Build a small image on top of the WordPress one that installs Xdebug from PECL, then point it at your editor. The official image ships pecl and the docker-php-ext-enable helper but not Xdebug. Xdebug 3.5.3 is the PECL release on 15 Nov 2026, and the Dockerfile below built and loaded on PHP 8.3.36.
FROM wordpress:7.1.4-php8.3-apache
RUN apt-get update \
&& apt-get install -y --no-install-recommends $PHPIZE_DEPS \
&& pecl install xdebug-3.5.3 \
&& docker-php-ext-enable xdebug \
&& apt-get purge -y --auto-remove $PHPIZE_DEPS \
&& rm -rf /var/lib/apt/lists/* /tmp/pear
COPY xdebug.ini /usr/local/etc/php/conf.d/zz-xdebug.iniCreate docker/xdebug/xdebug.ini next to it:
xdebug.mode = debug
xdebug.start_with_request = trigger
xdebug.client_host = host.docker.internal
xdebug.client_port = 9003Then change the wordpress service to build that image instead of pulling one. On Linux, add the extra_hosts line, because Docker Desktop defines host.docker.internal for you and Docker Engine on Linux does not:
wordpress:
build: ./docker/xdebug
extra_hosts:
- "host.docker.internal:host-gateway"
# keep the rest of the service as beforeThree settings carry the setup. xdebug.mode = debug turns on step debugging. xdebug.start_with_request = trigger means Xdebug connects only when a request carries a trigger, so normal page loads are not slowed down. xdebug.client_port = 9003 is Xdebug 3’s default port. To trigger a session, add ?XDEBUG_TRIGGER=1 to a URL or use a browser extension that sets the cookie; the Xdebug step debugging documentation describes the trigger values.
In VS Code with the PHP Debug extension, the path mapping is the part people get wrong. It must map the path inside the container to the path on your disk:
{
"version": "0.2.0",
"configurations": [
{
"name": "Listen for Xdebug",
"type": "php",
"request": "launch",
"port": 9003,
"pathMappings": {
"/var/www/html/wp-content/plugins/my-plugin": "${workspaceFolder}/plugins/my-plugin"
}
}
]
}If breakpoints never hit, check in this order: the editor is listening on 9003, the container can resolve host.docker.internal, a trigger is present on the request, and the path mapping matches. If you use wp-env instead, none of this is needed: wp-env start --xdebug turns it on.
How do you catch outgoing email in a local Docker site?
The WordPress image has no mail server, so wp_mail() fails quietly. The usual fix is a mail catcher container that accepts SMTP and shows messages in a web inbox. We use Mailpit (release v1.33.1, 7 Nov 2026), which the Compose file above already defines under the mail profile. Start it with docker compose --profile mail up -d; the inbox is at http://localhost:8025. We confirmed that image tag exists but did not send test mail through it in this pass.
Then point WordPress at it with a must-use plugin. Save this as mu-plugins/mail.php and add ./mu-plugins:/var/www/html/wp-content/mu-plugins to the volumes of wordpress. It uses core’s phpmailer_init action, and it passed php -l:
<?php
/**
* Plugin Name: Local mail catcher
* Description: Sends wp_mail() to the Mailpit container. Local development only.
*/
add_action( 'phpmailer_init', function ( $phpmailer ) {
$phpmailer->isSMTP();
$phpmailer->Host = 'mailpit';
$phpmailer->Port = 1025;
$phpmailer->SMTPAuth = false;
$phpmailer->SMTPAutoTLS = false;
} );This file is for local use only. Never commit it into a plugin you ship.
Why is Docker slow on macOS, and how do you fix it?
Docker on macOS runs Linux in a virtual machine, so every file your container reads from a folder on your Mac crosses that boundary. WordPress reads hundreds of PHP files per request, so mounting the whole site from your disk is the slow path. Three changes help, in order of effect:
- Keep WordPress core inside a named volume, as the Compose file does, and mount only the code you edit.
- Use VirtioFS file sharing. In Docker Desktop’s settings you can choose VirtioFS or gRPC FUSE; Docker’s documentation says VirtioFS cut filesystem operation time by up to 98 percent and that it is the only option supported by Docker VMM.
- Try another Docker provider. The wp-env README suggests Colima as a free, GUI-less option on macOS. DDEV’s documentation recommends OrbStack as the most performant and easiest to install, and notes that it is commercial and not free for professional use.
Docker Desktop itself is free for personal use, education, non-commercial open source and small businesses (fewer than 250 employees and under 10 million US dollars in annual revenue), and needs a paid subscription for larger organisations, per Docker’s license page on 15 Nov 2026.
How do you fix file permission errors in Docker WordPress?
Most permission errors come from one fact: www-data is a different user in the two images. We checked it by running id in both on 15 Nov 2026.
Image | Base | www-data user ID |
|---|---|---|
| Debian | 33 |
| Alpine | 82 |
Files created by Apache belong to user 33. A WP-CLI container running as 82 cannot write to them. We reproduced this: wp config set run as 82:82 stopped with “wp-config.php is not writable”, and the same command with user: "33:33" succeeded. That is why the Compose file sets the user on wpcli. For a one-off command you can pass it on the command line: docker compose run --rm --user 33:33 wpcli wp plugin install classic-editor --activate.
A second cause is bind-mounting a host folder straight over wp-content or one of its subfolders. The folder on your computer is owned by you, not by user 33, so WordPress cannot write uploads there. The image maintainers added wide permissions to the pre-created wp-content directories to soften this (pull request 503), but the clean answer is not to mount those folders at all. Keep uploads in the named volume and mount only plugin and theme source.
What is wp-env, and when is it simpler than Compose?
wp-env is the Docker-based tool the Gutenberg project maintains. You describe the environment in a small .wp-env.json file and it creates the containers, installs WordPress and mounts your plugin. It is simpler than Compose when you build one plugin or theme, want tests, and do not need to tune the stack. According to the package README for @wordpress/env 12.1.0 (published 4 Nov 2026), it needs Docker with Compose v2 and Node 22.13 or newer, serves the site at http://localhost:8888 with user admin and password password, and reserves port 8889 for a test site.
cd /path/to/your/plugin
npm -g i @wordpress/env
wp-env startA minimal config that pins the versions looks like this. The field names come from the README table:
{
"$schema": "https://schemas.wp.org/trunk/wp-env.json",
"phpVersion": "8.3",
"mariadbVersion": "11.8",
"plugins": [ "." ],
"phpmyadmin": true
}Useful details from the README, none of which we ran ourselves this time:
wp-env run cli wp user listruns WP-CLI in the CLI container, andwp-env run cli composer installruns Composer.wp-env start --xdebugenables step debugging; withnpm runyou need the extra double dash:npm run wp-env start -- --xdebug.- Ports 8888 and 8889 are fixed by default. Set
"autoPort": trueor pass--auto-portto let it find free ones, which it does not do when theCIvariable is set. wp-env cleanupremoves containers, volumes and local files but keeps images;wp-env destroyremoves the environment entirely.- Version 12 added two experimental runtimes that need no Docker,
--runtime=playgroundand--runtime=php. The PHP runtime uses SQLite, has no multisite, and cannot runwp-env run.
The trade-off is control. Adding Redis, Mailpit or a second site means fighting the tool or switching to your own Compose file. We use wp-env for single-plugin work and Compose when a project needs extra services.
What about DDEV and Lando for WordPress?
Both sit on top of Docker and aim to make the setup repeatable. DDEV’s quickstart for WordPress is a handful of commands: ddev config --project-type=wordpress, ddev start, ddev wp core download and ddev wp core install, with the site served at an HTTPS address ending in .ddev.site. DDEV’s release page showed v1.25.5 on 26 October 2026, and its docs list OrbStack, Lima, Docker Desktop, Rancher Desktop and Colima as supported Docker providers on macOS. DDEV is the one we would pick over writing Compose files for a team that runs many different projects.
Lando keeps its settings in a .lando.yml in each project, and its docs describe a WordPress recipe with configurable PHP versions. Its last release was v3.26.9 on 20 August 2026, nearly three months before this check. That is not a problem by itself, but weigh it against DDEV’s more recent cadence if you are choosing for a new team.
When are Local, Studio or Playground simpler than Docker?
Choose the non-Docker tool when the goal is a working WordPress site, not an environment that matches a server.
- Local creates a site in a few clicks and describes itself as including SSL, WP-CLI, root SSH access and PHP version switching. It suits designers, support work and anyone who does not want to read container logs.
- WordPress Studio is Automattic’s desktop app with a CLI and an AI agent called Studio Code; its documentation covers PHP runtimes, SSL with custom domains and Xdebug. Its requirements list names only the operating system. If you work with coding agents, our guide to AI agents and Playground over MCP shows the other side of this.
- Playground runs WordPress in WebAssembly, so it starts in a browser tab or from the command line with nothing installed. It is the fastest way to reproduce a bug for a forum post or test a Blueprint.
Docker still wins when production runs a specific PHP and MariaDB combination you need to match, when two developers must run identical stacks, or when a database-heavy plugin behaves differently on SQLite than on MariaDB. If you are unsure, start with the simple tool and move to containers the first time a bug appears on the server and not on your machine.
Common mistakes people report
These come up repeatedly in the official image’s issue tracker and the wp-env documentation. Checked 15 November 2026; each item links to its source.
- Mail never arrives. The image has no mail transfer agent, so
wp_mail()fails. The “Email does not work” issue was opened in 2014, is still open and has about 100 comments; the fix is an SMTP catcher as shown above. - WP-CLI cannot write files. The Alpine CLI image and the Debian WordPress image use different
www-dataIDs. One commenter on issue 256 settled on running the CLI with--user 33:33, which matches our own test. - The database connection error on first start. Reports such as issue 787 describe WordPress starting before MariaDB is ready or with mismatched credentials. Add the healthcheck, and remember that MariaDB ignores its
MARIADB_*variables once a data volume already holds a database, so changing the password in the file does nothing until you remove the volume. - Floating tags that change PHP under you. The plain and
latesttags follow the maintainers’ default PHP, and issue 959 shows they are discussing moving that default to a newer version after WordPress retired its beta-support label for PHP in May 2026 (see the core announcement). Pin the full tag. - wp-env flags swallowed by npm. Running
npm run wp-env start --xdebugwithout the extra--passes the flag to npm, which ignores it, so Xdebug stays off. The README says so directly. - Mounting the whole site from the host. It is slow on macOS and Windows and causes the ownership problems above. Mount only the plugin or theme you edit.
How do you stop, reset or remove a Docker WordPress site?
Goal | Command | Effect |
|---|---|---|
Pause |
| Containers stop, data stays |
Restart clean |
| Containers and network removed, volumes kept |
Start over |
| Also deletes the database and WordPress files |
See errors |
| Follows Apache and PHP output |
Read debug log |
| Needs |
Always use a project name or a separate folder per project. The name: key in the file keeps one project’s containers and volumes from colliding with another’s. Running docker compose down -v in the wrong folder deletes that project’s database, so check the folder first.
Frequently asked questions
Is Docker free for WordPress development?
Docker Engine is free. Docker Desktop is free for personal use, education, non-commercial open source and small businesses, and needs a paid plan for larger organisations. Colima, Lima and Rancher Desktop are free alternatives on a Mac; OrbStack is a commercial one.
Which PHP version should I use in a local Docker setup?
Match production. If you are free to choose, WordPress.org recommends PHP 8.3 or newer, and the image publishes 8.2 to 8.5. Test your code on the newest version you support before you upgrade a live site.
Should I use MariaDB or MySQL?
Use whichever your host runs. WordPress.org recommends MariaDB 10.11 or newer and MySQL 8.4 or newer. The two engines have diverged in places, so a mismatch with production can hide a bug.
How do I import an existing site into Docker?
Copy the database in with WP-CLI and the files into the volume. A typical route: docker compose exec -T db mariadb -uwp -pwp-dev-only wordpress < dump.sql, then wpd search-replace https://example.com http://localhost:8080 --all-tables, and copy wp-content/uploads into the container with docker compose cp. We did not test an import in this pass, so try it on a copy first.
Can I run several WordPress projects at once?
Yes. Give each project its own folder, its own name: and its own host port, or use DDEV, which handles names and ports for you.
Can I use this setup in production?
Not as written. The file uses a throwaway password, exposes the site over plain HTTP and mounts source from a laptop. Production containers need secrets handling, HTTPS, backups and image rebuilds on security releases. Treat this file as a development tool.
Why does my site show the wrong URL after I change the port?
WordPress stores its address in the database. Update it with wpd option update home http://localhost:8090 and wpd option update siteurl http://localhost:8090, or run wpd search-replace across the database.
Checked on 15 November 2026 against Docker Hub, the docker-library/wordpress issue tracker, the @wordpress/env README, the DDEV, Lando, Studio and Playground documentation, and a local run of the Compose file on Docker 29.9.2.





No comments yet