---
title: "WordPress Local Development: Install and Build Locally"
description: "Install WordPress locally with Local, MAMP or Docker. Develop and test your site without hosting."
date: "2026-03-18"
author: "ElevaSEO"
category: "WordPress"
tags: ["wordpress", "local", "development", "mamp", "docker"]
keywords: ["wordpress local development", "install wordpress locally", "local wordpress", "wordpress localhost", "wordpress local server", "docker wordpress", "mamp wordpress"]
image: "/blog/category-wordpress.webp"
published: true
locale: "en"
translationKey: "wordpress-local-guide"
imageAlt: "WordPress Local Development: Install and Build Locally"
lastmod: "2026-03-18"
authorImage: "/authors/elevaseo.webp"
authorTwitter: ""
isFamilyFriendly: true
---
Building a WordPress website directly on a live server is like performing surgery in a moving ambulance. Every change you make is immediately visible to your visitors, search engines crawl your half-finished pages, and a single PHP error can take down your entire site. The alternative is **WordPress local development**, a practice that every professional developer and agency considers non-negotiable.
A local WordPress installation runs entirely on your own computer. No hosting account needed. No domain required. No risk of breaking a live website while you experiment with a new theme, test plugin compatibility, or build a custom solution from scratch. The result is a faster, safer, and more efficient development workflow that separates the building phase from the production phase.
This guide covers four proven methods to **install WordPress locally**: Local by Flywheel, MAMP, Docker, and wp-env. Each method is presented with step-by-step instructions you can follow regardless of your operating system. Beyond installation, you will learn the development workflows, deployment strategies, and troubleshooting techniques that transform a simple local setup into a professional development environment.
Whether you are a freelancer building client sites, a developer maintaining a plugin, or a business owner who wants a safe testing ground, this article provides everything you need to run WordPress on your machine with confidence.
## Why develop WordPress locally?
The question is not whether you should develop locally. The question is why anyone would skip it. Local development delivers measurable advantages across speed, safety, cost, and workflow quality.
### Speed without network latency
A local WordPress installation responds in milliseconds. There is no network round-trip to a remote server, no shared hosting bottleneck, no CDN cache to warm up. Page loads happen almost instantly, which means you spend more time coding and less time waiting. When you are debugging a CSS layout or testing a WooCommerce checkout flow, that speed difference adds up to hours saved over a single project.
### Risk-free experimentation
On a local environment, you can break things freely. Update WordPress core to the latest version. Install an untested plugin. Switch themes. Modify the database schema. If something goes wrong, the damage is contained entirely on your machine. Your live site remains untouched, your visitors see no errors, and search engines never encounter broken pages.
### Offline capability
Local development does not require an internet connection. You can work on a train, on a plane, or in a location with unreliable connectivity. The entire WordPress stack (Apache or Nginx, PHP, MySQL) runs on your computer. This independence from connectivity is particularly valuable for developers who travel or work in environments where network access is restricted.
### Cost savings
A local development environment is free. You do not need to purchase a staging server, pay for a separate hosting plan, or maintain a dedicated testing domain. Tools like Local by Flywheel, MAMP (free tier), Docker, and wp-env all come at zero cost. For freelancers managing multiple client projects simultaneously, this removes a significant recurring expense.
### Version control integration
When your WordPress project lives on your local filesystem, integrating with Git becomes straightforward. You can track every change to your theme or plugin code, create branches for experimental features, and roll back to any previous state. This version-controlled workflow is nearly impossible to implement effectively on a remote server where files are managed through FTP or a hosting control panel.
**Professional standard.** In 2026, every major WordPress agency uses local development environments as the foundation of their workflow. It is not a shortcut or a convenience. It is a requirement for delivering reliable, well-tested WordPress projects.
## Prerequisites for local WordPress development
Before installing WordPress on your machine, verify that your system meets the minimum requirements. The good news is that modern computers almost universally exceed these thresholds.
### System requirements
- **Operating system.** Windows 10 or later, macOS 12 (Monterey) or later, or a mainstream Linux distribution (Ubuntu, Fedora, Debian).
- **RAM.** At minimum 4 GB, though 8 GB or more is recommended. Running a local server stack alongside your code editor and browser consumes memory.
- **Disk space.** WordPress itself requires roughly 100 MB. Factor in your database, uploaded media, and plugins, and plan for at least 1 GB per project.
- **Processor.** Any modern multi-core processor handles local development without difficulty. Virtualization support (VT-x or AMD-V) is required for Docker-based setups.
### Software you will need
Regardless of which installation method you choose, keep these tools available:
- **A code editor.** Visual Studio Code, PhpStorm, or Sublime Text. VS Code is the most popular choice due to its WordPress-specific extensions and integrated terminal.
- **A web browser with developer tools.** Chrome, Firefox, or Edge. The developer tools panel is essential for debugging CSS, inspecting network requests, and profiling performance.
- **A terminal application.** The built-in terminal on macOS and Linux, or Windows Terminal on Windows. Several installation methods require command-line interaction.
### WordPress itself
Download the latest version of WordPress from [wordpress.org/download](https://wordpress.org/download/). Some tools like Local by Flywheel handle this download automatically, but having a copy available is useful for manual setups.
## Method 1: Local by Flywheel (recommended for beginners)
**Local** (formerly Local by Flywheel) is a free, purpose-built application for WordPress local development. It provides a graphical interface that eliminates the need to configure Apache, MySQL, and PHP manually. Creating a new WordPress site takes less than two minutes.
### Why Local stands out
Local is designed exclusively for WordPress. Unlike general-purpose server stacks, every feature targets the WordPress development workflow:
- **One-click site creation.** Specify a site name, choose your PHP version and web server (Apache or Nginx), and Local handles everything else.
- **SSL support.** Local generates trusted SSL certificates automatically, allowing you to test HTTPS functionality without additional configuration.
- **Live Links.** Share your local site with clients or collaborators through a temporary public URL. No deployment required.
- **MagicSync and cloud backups.** Push your local site to Flywheel or WP Engine hosting with a single click (requires a hosting account).
- **Add-ons ecosystem.** Extend Local with tools like image optimization, link checking, and instant reload.
### Step-by-step installation
**Step 1: Download and install Local.**
Visit [localwp.com](https://localwp.com/) and download the installer for your operating system. Run the installer and follow the on-screen prompts. On macOS, drag the application to your Applications folder. On Windows, the installer handles placement automatically.
**Step 2: Create a new site.**
Launch Local and click the **Create a new site** button. Choose **Create a new site** (not "Create from Blueprint").
Enter a name for your site. This name also determines the local domain. For example, naming your site "my-project" creates the domain `my-project.local`.
**Step 3: Choose your environment.**
Local presents two options:
- **Preferred.** Uses the default PHP version, web server (Nginx), and MySQL version. This is the fastest path for most projects.
- **Custom.** Lets you select specific versions of PHP (7.4 through 8.3), choose between Nginx and Apache, and select your MySQL version.
For most WordPress development, the Preferred option works well. Choose Custom only when you need to match a specific production server configuration.
**Step 4: Set up WordPress credentials.**
Enter a WordPress username, password, and email address. These credentials are for the local WordPress admin dashboard. Since this is a local-only installation, security requirements are relaxed, but using realistic credentials helps you test authentication flows.
**Step 5: Start building.**
Click **Add Site**. Local downloads and configures all necessary components. Within one to two minutes, your WordPress site is running. Click **Open Site** to view the frontend, or **WP Admin** to access the dashboard.
### Managing multiple sites
Local excels at managing multiple WordPress installations simultaneously. Each site gets its own isolated environment with independent PHP versions, databases, and configurations. This is particularly valuable for agencies that maintain dozens of client sites, each potentially running different WordPress and PHP versions.
To stop a site and free system resources, right-click the site name and select **Stop site**. Stopped sites retain all their data and can be restarted instantly.
### Local's built-in database manager
Local includes **Adminer**, a lightweight database management tool accessible directly from the application interface. Click the **Database** tab for any site to open Adminer in your browser. From there, you can browse tables, run SQL queries, export data, and import database dumps. This eliminates the need to install phpMyAdmin or a standalone database client.
## Method 2: MAMP (classic cross-platform solution)
**MAMP** stands for macOS, Apache, MySQL, and PHP, though it now runs on Windows as well. It has been a staple of local development for over a decade and remains a solid choice for developers who want direct control over their server stack.
### Free vs. Pro
MAMP comes in two versions:
- **MAMP Free.** Includes Apache, MySQL, and PHP. Sufficient for most WordPress development. Limited to a single document root.
- **MAMP Pro.** Adds Nginx support, virtual hosts (multiple sites), dynamic DNS, email testing, and a visual host editor. The Pro license costs approximately $40 as a one-time purchase.
For straightforward WordPress development, the free version handles the job. The Pro version becomes valuable when you need to run multiple local sites simultaneously or require features like local email testing.
### Step-by-step installation
**Step 1: Download and install MAMP.**
Visit [mamp.info](https://www.mamp.info/) and download the installer for macOS or Windows. Run the installer and accept the default settings. On macOS, MAMP installs to `/Applications/MAMP/`. On Windows, it installs to `C:\MAMP\`.
**Step 2: Start the servers.**
Launch the MAMP application and click **Start Servers**. The status indicators for Apache and MySQL should turn green, confirming that both services are running. By default, Apache runs on port 8888 and MySQL on port 8889.
**Step 3: Create a database.**
Open your browser and navigate to `http://localhost:8888/phpMyAdmin/` (or click **Open WebStart Page** in MAMP, then navigate to **Tools > phpMyAdmin**).
In phpMyAdmin, click **New** in the left sidebar. Enter a database name (for example, `wordpress_dev`) and select `utf8mb4_general_ci` as the collation. Click **Create**.
**Step 4: Download and place WordPress.**
Download WordPress from [wordpress.org/download](https://wordpress.org/download/) and extract the archive. Move the extracted `wordpress` folder into the MAMP document root:
- **macOS:** `/Applications/MAMP/htdocs/`
- **Windows:** `C:\MAMP\htdocs\`
Rename the folder to something meaningful, such as `my-project`.
**Step 5: Run the WordPress installer.**
Open your browser and navigate to `http://localhost:8888/my-project/`. WordPress displays its installation wizard. Enter the following database details:
- **Database Name:** `wordpress_dev` (the name you created in Step 3)
- **Username:** `root`
- **Password:** `root`
- **Database Host:** `localhost`
- **Table Prefix:** `wp_` (or a custom prefix for better security practices)
Click **Submit**, then **Run the installation**. Fill in your site title, admin username, password, and email. Click **Install WordPress**.
Your local WordPress site is now accessible at `http://localhost:8888/my-project/`.
### Configuring PHP settings
MAMP allows you to adjust PHP settings that affect WordPress behavior. Common adjustments include:
- **upload_max_filesize.** Increase this value if you need to upload large media files or import database dumps. The default is typically 2 MB or 8 MB.
- **max_execution_time.** Extend this for operations that take longer than the default 30 seconds, such as importing large datasets or running migration plugins.
- **memory_limit.** WordPress recommends at least 256 MB. Set this value in the MAMP PHP configuration or in your site's `wp-config.php` file with `define('WP_MEMORY_LIMIT', '256M');`.
On MAMP for macOS, PHP configuration files are located at `/Applications/MAMP/bin/php/phpX.X.X/conf/php.ini`. On Windows, the path is `C:\MAMP\bin\php\phpX.X.X\php.ini`.
## Method 3: Docker (for professional workflows)
**Docker** takes a fundamentally different approach to local development. Instead of installing server software directly on your machine, Docker runs each service (WordPress, MySQL, phpMyAdmin) inside lightweight, isolated containers. This guarantees that your development environment is identical to your production environment, eliminating the "it works on my machine" problem.
### Why Docker for WordPress
Docker offers advantages that matter most in professional and team-based development:
- **Environment parity.** Your local setup mirrors production exactly. Same PHP version, same MySQL version, same extensions.
- **Reproducibility.** A single `docker-compose.yml` file defines your entire stack. Share it with your team, and everyone runs the same environment.
- **Isolation.** Each project gets its own containers. No port conflicts, no shared databases, no dependency collisions.
- **Disposability.** Destroy and recreate your environment in seconds. Corrupted database? Delete the container and start fresh.
### Prerequisites
Install **Docker Desktop** from [docker.com](https://www.docker.com/products/docker-desktop/). Docker Desktop is free for personal use and small businesses. It runs on Windows (with WSL 2), macOS, and Linux.
Verify the installation by opening a terminal and running:
```bash
docker --version
docker compose version
```
Both commands should return version numbers.
### Step-by-step setup with docker-compose
**Step 1: Create a project directory.**
```bash
mkdir wordpress-local && cd wordpress-local
```
**Step 2: Create the docker-compose.yml file.**
Create a file named `docker-compose.yml` in your project directory with the following content:
```yaml
services:
wordpress:
image: wordpress:latest
ports:
- "8080:80"
environment:
WORDPRESS_DB_HOST: db
WORDPRESS_DB_USER: wordpress
WORDPRESS_DB_PASSWORD: wordpress
WORDPRESS_DB_NAME: wordpress
volumes:
- ./wp-content:/var/www/html/wp-content
- wordpress_data:/var/www/html
depends_on:
- db
restart: unless-stopped
db:
image: mysql:8.0
environment:
MYSQL_DATABASE: wordpress
MYSQL_USER: wordpress
MYSQL_PASSWORD: wordpress
MYSQL_ROOT_PASSWORD: rootpassword
volumes:
- db_data:/var/lib/mysql
restart: unless-stopped
phpmyadmin:
image: phpmyadmin:latest
ports:
- "8081:80"
environment:
PMA_HOST: db
MYSQL_ROOT_PASSWORD: rootpassword
depends_on:
- db
restart: unless-stopped
volumes:
wordpress_data:
db_data:
```
**Step 3: Launch the stack.**
```bash
docker compose up -d
```
Docker downloads the required images (WordPress, MySQL, phpMyAdmin) and starts the containers. The first run takes a few minutes due to image downloads. Subsequent starts complete in seconds.
**Step 4: Complete the WordPress installation.**
Open your browser and navigate to `http://localhost:8080`. The WordPress installation wizard appears. Complete it with your preferred site title, username, and password.
phpMyAdmin is accessible at `http://localhost:8081` for direct database management.
**Step 5: Develop with mounted volumes.**
Notice the volume mount in the docker-compose file: `./wp-content:/var/www/html/wp-content`. This maps the `wp-content` directory inside the container to a folder on your local filesystem. Any changes you make to theme files, plugin code, or uploaded media in the `wp-content` folder on your machine are immediately reflected in the running WordPress installation.
This is the key to productive Docker-based WordPress development. Edit files in your code editor, save, and refresh the browser.
### Useful Docker commands
```bash
# Stop all containers
docker compose down
# Stop containers and delete all data (fresh start)
docker compose down -v
# View container logs
docker compose logs wordpress
# Access the WordPress container shell
docker compose exec wordpress bash
# Restart only the WordPress container
docker compose restart wordpress
```
**Persistent vs. ephemeral data.** The `volumes` section in docker-compose.yml determines what data survives a container restart. Named volumes like `db_data` persist your database. The bind mount `./wp-content` keeps your theme and plugin files on your local disk. If you run `docker compose down -v`, named volumes are deleted and you lose your database. The bind-mounted `wp-content` folder remains intact on your filesystem.
### Adding WP-CLI to your Docker setup
WP-CLI is the command-line interface for WordPress. Adding it to your Docker setup enables powerful automation:
```yaml
wpcli:
image: wordpress:cli
environment:
WORDPRESS_DB_HOST: db
WORDPRESS_DB_USER: wordpress
WORDPRESS_DB_PASSWORD: wordpress
WORDPRESS_DB_NAME: wordpress
volumes:
- wordpress_data:/var/www/html
- ./wp-content:/var/www/html/wp-content
depends_on:
- db
- wordpress
entrypoint: wp
command: "--info"
```
Run WP-CLI commands through Docker:
```bash
# Install a plugin
docker compose run --rm wpcli plugin install woocommerce --activate
# Export the database
docker compose run --rm wpcli db export /var/www/html/wp-content/backup.sql
# Update WordPress core
docker compose run --rm wpcli core update
```
## Method 4: wp-env (official WordPress developer tool)
**wp-env** is the official local development tool maintained by the WordPress core team. It is built on Docker and designed specifically for WordPress plugin and theme development. If you contribute to WordPress core or build plugins for the directory, wp-env is the standard tool.
### When to use wp-env
wp-env shines in specific scenarios:
- **Plugin and theme development.** It maps your plugin or theme directory directly into a running WordPress installation.
- **Contributing to WordPress core.** wp-env is the recommended environment for core development and testing.
- **Automated testing.** It integrates cleanly with PHPUnit and end-to-end testing frameworks.
For general website development (building client sites, customizing themes for specific projects), Local by Flywheel or Docker offer more flexibility.
### Installation
wp-env requires Node.js (version 18 or later) and Docker. Install it globally with npm:
```bash
npm install -g @wordpress/env
```
Verify the installation:
```bash
wp-env --version
```
### Setting up a project
**Step 1: Navigate to your plugin or theme directory.**
```bash
cd my-wordpress-plugin
```
**Step 2: Start the environment.**
```bash
wp-env start
```
wp-env downloads WordPress, creates a Docker-based environment, and mounts your current directory as a plugin (or theme, depending on the directory structure). Your site is available at `http://localhost:8888` with the admin dashboard at `http://localhost:8888/wp-admin/` (username: `admin`, password: `password`).
**Step 3: Configure with .wp-env.json.**
Create a `.wp-env.json` file in your project root for custom configuration:
```json
{
"core": "WordPress/WordPress#6.7",
"plugins": [
".",
"https://downloads.wordpress.org/plugin/woocommerce.latest-stable.zip"
],
"themes": [
"https://downloads.wordpress.org/theme/flavor.latest-stable.zip"
],
"phpVersion": "8.2",
"config": {
"WP_DEBUG": true,
"WP_DEBUG_LOG": true,
"SCRIPT_DEBUG": true
}
}
```
This configuration pins a specific WordPress version, installs additional plugins alongside your project, sets the PHP version, and enables debug constants.
### Useful wp-env commands
```bash
# Stop the environment
wp-env stop
# Destroy the environment (fresh start)
wp-env destroy
# Run WP-CLI commands
wp-env run cli wp plugin list
# Run PHPUnit tests
wp-env run tests-cli phpunit
# Clean the database
wp-env clean all
```
## Comparing local development tools
Choosing the right tool depends on your experience level, project requirements, and team workflow. The following comparison highlights the key differences.
### Feature-by-feature breakdown
**Local by Flywheel** is the best choice for most WordPress users. Its graphical interface eliminates the learning curve, site creation takes two minutes, and features like Live Links and built-in SSL set it apart. The only limitation is that it runs exclusively on desktop operating systems and does not support non-WordPress projects.
**MAMP** offers a traditional approach that many developers have relied on for years. It provides direct control over Apache, MySQL, and PHP configurations. The free version is limited to a single document root, which makes juggling multiple projects inconvenient without the Pro upgrade. MAMP is a good choice if you need a general-purpose local server that can handle WordPress alongside other PHP projects.
**Docker** provides the highest level of control and reproducibility. Environment parity with production servers eliminates deployment surprises. The learning curve is steeper, and Docker Desktop consumes more system resources. Docker is the professional choice for teams that need consistent, version-controlled environments across multiple developers.
**wp-env** is purpose-built for plugin and theme development. Its tight integration with the WordPress development ecosystem makes it the right tool for contributors and plugin authors. For general website building, it lacks the convenience features (GUI, SSL, Live Links) that Local provides.
### Which tool should you choose?
- **You are a beginner or a freelancer building client sites:** Use **Local by Flywheel**. The visual interface and WordPress-specific features save time on every project.
- **You need a general-purpose local server:** Use **MAMP**. It handles WordPress alongside Laravel, Drupal, or any PHP application.
- **You work in a team and need environment consistency:** Use **Docker**. The docker-compose.yml file ensures every developer runs the exact same stack.
- **You develop plugins or themes for the WordPress directory:** Use **wp-env**. It integrates with the WordPress testing infrastructure.
## Essential development workflow
Installing WordPress locally is the first step. Building an efficient development workflow transforms that installation into a professional toolchain.
### Enabling debug mode
WordPress includes a built-in debugging system that is disabled by default. Enable it by adding these constants to your `wp-config.php` file:
```php
define('WP_DEBUG', true);
define('WP_DEBUG_LOG', true);
define('WP_DEBUG_DISPLAY', false);
define('SCRIPT_DEBUG', true);
define('SAVEQUERIES', true);
```
- **WP_DEBUG** activates error reporting.
- **WP_DEBUG_LOG** writes errors to `wp-content/debug.log` instead of displaying them on screen.
- **WP_DEBUG_DISPLAY** set to `false` prevents errors from appearing in the browser output, keeping your frontend clean while still logging issues.
- **SCRIPT_DEBUG** forces WordPress to use unminified versions of core CSS and JavaScript files, making them easier to debug.
- **SAVEQUERIES** stores every database query in memory, accessible through the `$wpdb->queries` array. Useful for identifying slow or redundant queries.
### Using WP-CLI for rapid development
**WP-CLI** is the command-line interface for WordPress. It accelerates every common task:
```bash
# Install and activate a plugin
wp plugin install advanced-custom-fields --activate
# Create a new custom post type
wp scaffold post-type product --label="Product" --textdomain="my-theme"
# Generate dummy content for testing
wp post generate --count=50 --post_type=post
# Search and replace URLs (useful when migrating)
wp search-replace 'http://localhost:8080' 'https://example.com' --dry-run
# Export the database
wp db export backup.sql
# Import a database
wp db import production-dump.sql
```
WP-CLI is included in Local by Flywheel (accessible through the site shell) and can be added to Docker setups as shown in the Docker section above.
### Version control with Git
Track your WordPress project with Git to maintain a complete history of changes and enable collaboration. A well-structured `.gitignore` file is essential:
```
# WordPress core (do not track core files)
/wp-admin/
/wp-includes/
/wp-*.php
/index.php
/license.txt
/readme.html
/xmlrpc.php
# Configuration
wp-config.php
# Uploads (too large for version control)
wp-content/uploads/
# Dependencies
wp-content/plugins/*
!wp-content/plugins/my-custom-plugin/
wp-content/themes/*
!wp-content/themes/my-custom-theme/
# System files
.DS_Store
Thumbs.db
*.log
```
This `.gitignore` tracks only your custom theme and plugin code while excluding WordPress core, uploads, and third-party plugins. Third-party plugins should be managed through a dependency system like **Composer** or documented in a requirements file.
### Database management best practices
Your local WordPress database is the core of your site's content. Handle it carefully:
- **Regular exports.** Before making significant changes, export your database with `wp db export` or through phpMyAdmin/Adminer.
- **Meaningful table prefixes.** Use a project-specific table prefix (such as `proj_` instead of `wp_`) to avoid confusion when managing multiple databases.
- **Separate databases per project.** Never share a database between multiple WordPress installations. Each project should have its own isolated database.
- **Search-replace for URLs.** When moving databases between environments, use `wp search-replace` to update serialized data safely. Never use a text editor for find-and-replace on SQL dumps, as this corrupts serialized PHP arrays.
## Deploying from local to production
The moment arrives when your local WordPress site is ready for the world. Deployment is the process of moving your local installation to a live server. Done correctly, it takes minutes and preserves every aspect of your site.
### Manual deployment workflow
**Step 1: Export your local database.**
```bash
wp db export local-export.sql
```
**Step 2: Search-replace the local URL with the production URL.**
```bash
wp search-replace 'http://localhost:8080' 'https://yourdomain.com' --export=production.sql
```
This command creates a new SQL file with all URL references updated for production.
**Step 3: Upload your files.**
Transfer your WordPress files to the production server using SFTP, rsync, or your hosting provider's file manager. Ensure that file permissions are set correctly:
- **Directories:** 755
- **Files:** 644
- **wp-config.php:** 600 (or 440 for additional security)
**Step 4: Import the database.**
On the production server, create a new MySQL database and user. Import the production SQL file:
```bash
wp db import production.sql
```
Or use phpMyAdmin to import the file through the browser interface.
**Step 5: Update wp-config.php.**
Update the database credentials in `wp-config.php` to match the production server's MySQL settings.
**Step 6: Verify.**
Visit your production URL. Check that all pages load correctly, images display properly, and internal links point to the production domain. Run a crawl with a tool like Screaming Frog to catch any remaining localhost references.
### Plugin-based deployment
Several WordPress plugins simplify the local-to-production workflow:
- **All-in-One WP Migration.** Exports your entire site (database, media, plugins, themes) as a single downloadable file. Import it on the production server with the same plugin. Size limits apply on the free version.
- **Duplicator.** Creates a complete package of your WordPress installation. The package includes an installer script that handles database creation, search-replace, and file extraction on the destination server.
- **WP Migrate.** Performs database migration with search-replace built in. The Pro version supports media file migration and CLI integration.
### Continuous deployment for teams
For teams using Docker and Git, consider a continuous deployment pipeline:
1. **Push code to a Git repository** (GitHub, GitLab, or Bitbucket).
2. **A CI/CD pipeline** (GitHub Actions, GitLab CI) runs automated tests (PHPUnit, end-to-end tests).
3. **On success, the pipeline deploys** to a staging environment for review.
4. **After approval, deploy to production** using rsync, SSH, or a deployment tool like Deployer.
This workflow eliminates manual file transfers and ensures that every change is tested before reaching production. For a deeper look at hosting environments that support this workflow, consult our guide on [WordPress hosting comparison](/blog/wordpress/wordpress-hosting-comparison).
## Troubleshooting common local development issues
Local development environments introduce their own set of problems. Here are the most frequent issues and their solutions.
### Port conflicts
**Symptom:** Apache or MySQL fails to start. The error log mentions "port already in use."
**Cause:** Another application on your system is using the same port. Common culprits include Skype (port 80), other local servers, or system services.
**Solution:**
- **In Local:** Right-click the site, choose **Site settings**, and change the port numbers.
- **In MAMP:** Open **Preferences > Ports** and set Apache to 8888 and MySQL to 8889 (or any available ports).
- **In Docker:** Change the port mapping in `docker-compose.yml`. For example, change `"8080:80"` to `"8082:80"`.
- **General:** Run `lsof -i :80` (macOS/Linux) or `netstat -aon | findstr :80` (Windows) to identify which process is using the port.
### Database connection errors
**Symptom:** WordPress displays "Error establishing a database connection."
**Cause:** The database credentials in `wp-config.php` do not match the actual MySQL configuration.
**Solution:**
1. Verify that MySQL is running. In MAMP, check the server status indicators. In Docker, run `docker compose ps` and confirm the database container is "Up."
2. Confirm the database name, username, password, and host in `wp-config.php`.
3. For MAMP, the default credentials are `root` / `root` with host `localhost`.
4. For Docker, verify the environment variables in `docker-compose.yml` match your `wp-config.php` values.
5. If DB_HOST is `localhost`, try `127.0.0.1` instead. Some systems resolve these differently.
### White screen of death (WSOD)
**Symptom:** WordPress displays a blank white page with no error message.
**Cause:** A fatal PHP error is occurring, but error display is disabled.
**Solution:**
1. Enable debugging in `wp-config.php`: set `WP_DEBUG` to `true` and `WP_DEBUG_DISPLAY` to `true`.
2. Check `wp-content/debug.log` for error messages.
3. If the error points to a specific plugin or theme, rename the offending folder via the file system to deactivate it.
4. For a comprehensive guide to diagnosing this issue, refer to our article on [fixing the WordPress white screen of death](/blog/wordpress/white-screen-death-fix).
### PHP version incompatibilities
**Symptom:** Errors like "Parse error: syntax error" or "Call to undefined function" after updating PHP.
**Cause:** A plugin or theme uses PHP syntax or functions that are deprecated or removed in the newer PHP version.
**Solution:**
1. In Local, switch to an older PHP version through the site settings panel.
2. In MAMP, change the PHP version in **Preferences > PHP**.
3. In Docker, change the WordPress image tag. For example, use `wordpress:php8.1` instead of `wordpress:latest`.
4. Test each plugin individually to identify the incompatible one. Update it or find an alternative.
### Slow local performance
**Symptom:** Pages take several seconds to load on your local installation.
**Cause:** On macOS, Docker's file system performance can be slow due to how volumes are mounted. On any OS, unoptimized database queries or memory-intensive plugins contribute to slowness.
**Solution:**
- **Docker on macOS:** Use the `delegated` or `cached` volume mount strategy, or switch to the VirtioFS file sharing implementation in Docker Desktop settings.
- **All tools:** Disable plugins you are not actively testing. Each active plugin adds PHP execution time.
- **Database:** Run `wp db optimize` to defragment tables. Delete post revisions with `wp post delete $(wp post list --post_type=revision --format=ids)`.
- **Memory:** Increase the PHP memory limit in `wp-config.php` with `define('WP_MEMORY_LIMIT', '512M');`.
### Email not sending from localhost
**Symptom:** WordPress forms, password resets, and notifications do not send emails.
**Cause:** Your local machine does not have a configured mail server (SMTP).
**Solution:**
- **Local:** Install the **Mailhog** add-on from the Local add-ons library. Mailhog intercepts all outgoing emails and displays them in a browser interface.
- **MAMP Pro:** Configure the built-in Postfix mail server through the MAMP Pro preferences.
- **Docker:** Add a Mailhog container to your `docker-compose.yml`:
```yaml
mailhog:
image: mailhog/mailhog
ports:
- "1025:1025"
- "8025:8025"
```
Access the Mailhog interface at `http://localhost:8025` to view captured emails.
- **All setups:** Install a plugin like **WP Mail SMTP** and configure it to use an external SMTP service (such as Gmail or Mailtrap) for testing email delivery.
## Advanced local development techniques
Beyond basic installation and workflow, several advanced techniques elevate your local development environment.
### Multisite configuration
To test a WordPress Multisite network locally, add these constants to `wp-config.php` before running the network setup:
```php
define('WP_ALLOW_MULTISITE', true);
```
After activating this constant, visit **Tools > Network Setup** in the WordPress admin to configure either a subdomain or subdirectory-based multisite network. Subdirectory networks work more reliably in local environments since they do not require wildcard DNS configuration.
### Importing a production site locally
Working on a copy of a live site is one of the most common local development scenarios. The cleanest approach:
1. **Export the production database** using WP-CLI (`wp db export`) or phpMyAdmin.
2. **Download the production wp-content directory** via SFTP or rsync.
3. **Import the database** into your local environment.
4. **Run search-replace** to update all production URLs to your local domain:
```bash
wp search-replace 'https://yourdomain.com' 'http://localhost:8080' --all-tables
```
5. **Flush permalinks** by visiting **Settings > Permalinks** and clicking **Save Changes**.
6. **Regenerate thumbnails** if image sizes differ between environments: `wp media regenerate --yes`.
### Performance profiling
Local environments are ideal for performance analysis because you control every variable. Install the **Query Monitor** plugin to inspect:
- Database queries (count, execution time, and caller)
- PHP errors and warnings
- HTTP API requests
- Conditional checks and matched rewrite rules
- Enqueued scripts and styles
For deeper profiling, tools like **Xdebug** (available in Local and Docker environments) provide line-by-line execution analysis, stack traces, and memory consumption reports.
### Automated testing
Local environments support automated testing workflows that are impractical on live servers:
- **PHPUnit** for unit testing plugin and theme functions.
- **Playwright** or **Cypress** for end-to-end browser testing.
- **PHP_CodeSniffer** with the WordPress coding standards for code quality enforcement.
wp-env includes a dedicated testing instance accessible at `http://localhost:8889`, preconfigured for running WordPress test suites.
## Security considerations for local development
A local environment is inherently more secure than a production server because it is not exposed to the internet. However, certain practices ensure that your local development habits do not create security risks when you deploy to production.
- **Never use production credentials locally.** Use separate database passwords, API keys, and admin credentials for your local installation. If your local machine is compromised, production systems remain safe.
- **Do not commit sensitive files.** Your `.gitignore` should exclude `wp-config.php`, `.env` files, and any file containing API keys or passwords.
- **Keep local software updated.** Docker images, MAMP, and Local should be updated regularly to patch security vulnerabilities in Apache, MySQL, and PHP.
- **Use HTTPS even locally.** Local and most modern tools support local SSL certificates. Testing with HTTPS locally catches mixed-content issues before they appear in production.
For a comprehensive overview of WordPress security best practices that apply to both local and production environments, review our [WordPress security guide](/blog/wordpress/security-guide).
## Frequently asked questions
### Can I install WordPress locally without any coding experience?
Yes. **Local by Flywheel** provides a graphical interface that requires zero command-line interaction. Download the application, click "Create a new site," fill in a few fields, and your WordPress installation is ready. The entire process takes under three minutes. No knowledge of PHP, MySQL, Apache, or server configuration is necessary.
### What is the difference between localhost and a staging environment?
A **localhost** environment runs entirely on your computer. It is accessible only to you, costs nothing, and works offline. A **staging environment** is a copy of your production site hosted on a remote server, typically provided by your hosting company. Staging environments are useful for testing changes that depend on server-specific configurations (like email delivery or CDN behavior) and for getting client approval before pushing changes live. The ideal workflow uses both: develop locally, push to staging for review, then deploy to production.
### How do I access phpMyAdmin on my local WordPress installation?
The method depends on your tool:
- **Local by Flywheel:** Click the **Database** tab for your site and then click **Open Adminer**. Local uses Adminer rather than phpMyAdmin, but the functionality is equivalent.
- **MAMP:** Navigate to `http://localhost:8888/phpMyAdmin/` in your browser, or click **Open WebStart Page** and find the phpMyAdmin link under Tools.
- **Docker:** If your `docker-compose.yml` includes a phpMyAdmin service (as shown in the Docker section above), access it at `http://localhost:8081`.
- **wp-env:** Run `wp-env run cli wp db cli` to access the MySQL command line directly.
### Can I run WooCommerce on a local WordPress installation?
Absolutely. WooCommerce runs locally just like any other WordPress plugin. Install it through the WordPress admin dashboard or via WP-CLI (`wp plugin install woocommerce --activate`). You can configure products, test the checkout flow, and develop custom integrations entirely on your local machine. The only limitation is payment gateway testing, which requires internet connectivity and specific sandbox credentials from your payment provider (Stripe test keys, PayPal sandbox accounts).
## Moving forward with local development
WordPress local development is not an optional convenience. It is the foundation of every reliable WordPress workflow. By installing WordPress on your own machine, you gain the speed, safety, and control that remote development cannot provide.
Start with **Local by Flywheel** if you want the fastest path to a working environment. Graduate to **Docker** when your projects demand environment parity and team collaboration. Use **MAMP** when you need a general-purpose local server, and turn to **wp-env** when your work centers on plugin or theme contribution.
The tools covered in this guide are free, well-documented, and actively maintained. The investment is not financial. It is the decision to adopt a professional workflow that separates amateurs from experts.
For related WordPress topics, explore our guides on [WordPress maintenance](/blog/wordpress/maintenance-guide), [keeping WordPress updated](/blog/wordpress/wordpress-update-guide), and [installing WordPress on a live server](/blog/wordpress/install-wordpress-guide).