For years, setting up a local WordPress environment meant installing PHP, a web server and MySQL directly on your computer, then wrestling with versions whenever a project needed something different. One client site ran an older PHP version, another needed a newer one, a third had specific PHP extensions. Switching between them was a chore.
Docker changed that for me. Each project gets its own isolated environment, defined in a single file that lives with the project. It runs the same PHP and database versions as production, starts with one command and can be thrown away and rebuilt in minutes. When a teammate clones the project, they get exactly the same environment.
Desktop apps for local WordPress development are excellent for many people, and I still recommend them for simpler needs. But if you work on several projects with different requirements, Docker is worth learning. Here’s a practical setup.
What Docker gives you
- Consistency. Everyone on the project runs the same PHP version, extensions and database.
- Isolation. Projects don’t interfere with each other or with your computer’s own software.
- Production parity. You can match the PHP and database versions your live server uses.
- Disposability. Break something badly? Delete the containers and start again.
- Version control. The environment is defined in files you commit alongside your code.
The basic building blocks
A WordPress environment in Docker usually has:
- A WordPress container running PHP and a web server, from the official WordPress image.
- A database container running MariaDB or MySQL.
- Optionally, a WP-CLI container, a mail catcher and tools like phpMyAdmin or Adminer.
Docker Compose describes these containers and how they connect, in a file called compose.yaml or docker-compose.yml.
A practical Compose file
Here’s a setup I use as a starting point:
Start the environment:
Then open http://localhost:8080 to finish the WordPress installation, or install it with WP-CLI:
These credentials are for local development only. Never reuse them anywhere else.
Understanding the volumes
Volumes control what persists and what’s shared with your computer:
- db_data keeps the database between restarts.
- wp_core keeps WordPress core files inside Docker, which performs better than sharing them with your computer.
- Bind mounts for your theme and plugin folders map the code you’re working on from your project folder into the container. Edit files in your editor, and changes appear immediately.
Only mount the code you’re actively developing. Mounting the entire WordPress installation from your computer can be slow on some operating systems.
Match production versions
Use image tags that match your live server’s PHP version, like php8.2 or php8.3, and the same major version of MariaDB or MySQL. Testing locally on a newer PHP version than production is how “it works on my machine” bugs happen.
If production uses Nginx and PHP-FPM, you can use the FPM variant of the WordPress image with a separate Nginx container. For most development work, the Apache image is simpler and close enough, as long as you remember that Apache reads .htaccess files and Nginx doesn’t.
Importing a production database
To work with realistic content, import a copy of the production database:
Production databases contain personal data, like customer names, emails and orders. Handle them carefully. For many projects, anonymise customer data after importing, or use a sanitised copy, so real customer information doesn’t end up on developer laptops unnecessarily.
Catching outgoing email
Local environments shouldn’t send real emails to customers. Add a mail catcher container that captures all outgoing email and shows it in a web interface:
Then configure WordPress to send email through the mail catcher’s SMTP port, using a small must-use plugin or an SMTP plugin pointed at host mail and port 1025. Open http://localhost:8025 to see every email the site sends. It’s invaluable for testing WooCommerce order emails and form notifications.
Database access
For quick database inspection, add Adminer or phpMyAdmin as another service, or connect with a desktop database client by exposing the database port. Keep these tools local only.
File permissions
File permission issues are the most common Docker frustration. The web server inside the container runs as a specific user, often www-data with ID 33. Files created by WordPress, like uploads, belong to that user. Files you create on your computer belong to you.
Practical tips:
- Run WP-CLI as the same user as the web server, as in the example above with user 33:33.
- On Linux, you may need to adjust ownership or run containers with your own user ID.
- On macOS and Windows, Docker Desktop handles most permission mapping automatically.
Performance tips
- Avoid mounting the whole WordPress installation from your computer; mount only the code you develop.
- On macOS and Windows, use the file sharing options Docker Desktop recommends for better performance.
- Allocate enough memory to Docker in its settings.
- Enable OPcache for faster PHP, with timestamp validation enabled so code changes are picked up.
wp-env: an easier alternative
The WordPress project maintains a tool called wp-env, which uses Docker behind the scenes. It’s designed for plugin and theme development and testing, and requires almost no configuration:
A .wp-env.json file in your project defines which plugins and themes to load, the PHP version and other settings. wp-env includes a test environment and WP-CLI access. For plugin and block development, it’s often the quickest way to get started. For replicating a complex client site, a custom Compose setup gives more control.
Daily workflow
- Start: docker compose up -d
- Stop: docker compose down, which keeps volumes and data.
- Reset completely: docker compose down -v, which deletes volumes, including the database. Use with care.
- View logs: docker compose logs -f wordpress
- Run WP-CLI: docker compose run –rm wpcli wp plugin list
Commit the Compose file to your project repository, along with a short README explaining how to start the environment and import data.
Why I switched to Docker for client work
Before using Docker, I kept a local environment per PHP version and constantly switched between them. When a client’s production server ran an older PHP version than my laptop, I occasionally shipped code that worked locally and failed in production, because I’d used a newer language feature without noticing. Moving each project into its own Compose setup, pinned to the production PHP version, removed that whole class of problem.
It also made onboarding easier. When a second developer joined a project, they cloned the repository, ran one command, imported a sanitised database and were working within minutes. No setup document, no “it works differently on my machine” conversations.
And it made experiments safe. Testing a PHP upgrade, a new database version or a risky plugin update became a matter of changing an image tag, starting the environment and seeing what happened. If it broke, nothing outside the container was affected.
Common problems and fixes
- Port already in use: another application, or another project’s containers, is using the same port. Change the published port in the Compose file, like 8081 instead of 8080.
- Database connection errors on first start: the database container may still be initialising. Wait a few seconds, or add a health check so WordPress waits for the database.
- Changes not appearing: check that you’re editing files in the mounted folder, and clear any caching plugins or OPcache settings that don’t revalidate files.
- Slow page loads on macOS or Windows: reduce bind mounts to only the code you’re editing.
- Lost data after a reset: docker compose down -v deletes volumes, including the database. Export the database first if you need it.
Once it’s set up, you’ll rarely think about it again.
Share the setup
Add a short README to each project describing how to start Docker, import data and reach the mail catcher. New team members, and you in six months, will be grateful for those few lines.
Frequently asked questions
Is Docker better than local WordPress apps?
Not universally. Desktop apps are easier for single sites and non-technical users. Docker shines when you need exact version matching, multiple projects with different requirements or shared team environments.
Do I need to learn Docker deeply?
No. Understanding images, containers, volumes and Compose files covers most WordPress development needs. You can learn more as you go.
Why is my Docker WordPress site slow?
Often because the entire WordPress installation is mounted from your computer. Keep core inside a Docker volume and mount only the code you’re editing.
Can I use the same setup for production?
Docker can be used in production, but production needs different considerations: security hardening, backups, monitoring and scaling. Use local Docker setups for development unless you deliberately design a production container platform.
Final thoughts
Docker gives each WordPress project a consistent, isolated and disposable environment that matches production. Start with a simple Compose file for WordPress, a database and WP-CLI, mount only the code you’re developing, match production versions, catch outgoing email locally and handle real data responsibly. Once it’s set up, starting a project is a single command, and “it works on my machine” becomes far less common.




