WordPress Local Installation — Step-by-Step Guide with XAMPP, MAMP and Docker

In this tutorial, you'll install WordPress locally using XAMPP, MAMP, and Docker, then configure MySQL and PHP settings for development.

What You'll Learn

• Why local development matters for learning WordPress
• How to set up XAMPP on Windows and Linux
• How to set up MAMP on macOS
• How to use Docker for a clean WordPress environment
• How to create a MySQL database for WordPress
• How to configure wp-config.php (database settings, salts, table prefix)
• How to run the famous 5-minute install
• How to troubleshoot common installation problems

Why It Matters

Installing WordPress directly on a live server means every mistake — every broken theme, every experimental plugin — is visible to the world. Local development gives you a safe sandbox where you can break things, learn, and restart without consequences. Every professional WordPress developer works locally first.

Real-World Use

A developer needs to test a new plugin against the latest WordPress version, but their production site still runs on an older release. They set up a local environment, install the plugin, test compatibility, and only deploy if everything works. Without a local setup, they'd be testing blind on a live site.

Why Local Development First

Think of local development like a rehearsal before a live performance. You practice in private, make mistakes, fix them, and only when you're ready do you go on stage (the live server).

Benefits of local development:

• No internet required — work from a plane, a coffee shop, anywhere
• Instant feedback — save a file, refresh the browser, see the change
• Safe experimentation — a broken install takes 2 minutes to fix, not 2 hours
• Version control friendly — keep your entire site in Git
• Free — no hosting costs while you learn

Method 1: XAMPP (Cross-Platform)

XAMPP is a free, open-source package that bundles Apache, MySQL, PHP, and phpMyAdmin into a single install. It works on Windows, Linux, and macOS.

Step 1: Download and Install XAMPP

Go to apachefriends.org and download the version for your operating system. The installer includes Apache (web server), MySQL (database), PHP (the language WordPress is written in), and phpMyAdmin (database management tool).

Step 2: Start Apache and MySQL

Open the XAMPP Control Panel and click Start for both Apache and MySQL. Apache must be running to serve WordPress pages. MySQL must be running for the database.

# On Linux, after installing XAMPP, start it from the terminal:
sudo /opt/lampp/lampp start

Step 3: Create the Database

Open phpMyAdmin by visiting http://localhost/phpmyadmin. Click the Databases tab, enter a name (e.g., wordpress), choose utf8mb4_general_ci as the collation, and click Create.

-- phpMyAdmin runs this SQL when you create a database through the UI
CREATE DATABASE wordpress CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;

utf8mb4 is important. It supports emoji and special characters. The older utf8 charset only supports basic Unicode. Your users might paste an emoji in a comment — utf8mb4 handles that.

Step 4: Download WordPress

Visit wordpress.org/download, download the latest zip, and extract it into your XAMPP document root:

• Windows: C:\xampp\htdocs\wordpress
• Linux: /opt/lampp/htdocs/wordpress
• macOS: /Applications/XAMPP/htdocs/wordpress

Step 5: Configure wp-config.php

WordPress comes with a sample config file called wp-config-sample.php. Rename it to wp-config.php and open it in a text editor. This file tells WordPress how to connect to your database.

define( 'DB_NAME', 'wordpress' );
define( 'DB_USER', 'root' );
define( 'DB_PASSWORD', '' );
define( 'DB_HOST', 'localhost' );
define( 'DB_CHARSET', 'utf8mb4' );
define( 'DB_COLLATE', '' );

In XAMPP, the default MySQL user is root with no password. Never do this on a live site, but it's fine for local development.

Step 6: Add Security Salts

Salts are random strings used to encrypt cookies and passwords. If an attacker gets your database, salts make it much harder to decode user sessions. WordPress provides a salt generator:

define( 'AUTH_KEY',         'put your unique phrase here' );
define( 'SECURE_AUTH_KEY',  'put your unique phrase here' );
define( 'LOGGED_IN_KEY',    'put your unique phrase here' );
define( 'NONCE_KEY',        'put your unique phrase here' );
define( 'AUTH_SALT',        'put your unique phrase here' );
define( 'SECURE_AUTH_SALT', 'put your unique phrase here' );
define( 'LOGGED_IN_SALT',   'put your unique phrase here' );
define( 'NONCE_SALT',       'put your unique phrase here' );

Visit https://api.wordpress.org/secret-key/1.1/salt/ in your browser. Copy the output and paste it directly into wp-config.php, replacing the placeholder lines. This generates unique, random strings — do this for every WordPress installation.

Step 7: Change the Table Prefix

The default table prefix is wp_. Every WordPress installation uses this by default. If your site is the only one using the database, that's fine. But if an attacker tries a SQL Injection attack targeting wp_ tables, you become an easy target.

Change it to something unique:

$table_prefix = 'wp2e8j_';

A short prefix with letters and numbers is enough. Do not use wp_ for production sites.

Step 8: Run the 5-Minute Install

Open your browser and visit http://localhost/wordpress. You'll see the WordPress installation screen. Select your language, enter your site title, username, password, and email, then click Install WordPress.

flowchart TD
  A["Visit http://localhost/wordpress"] --> B["Select language"]
  B --> C["Enter site title"]
  C --> D["Create username and password"]
  D --> E["Enter admin email"]
  E --> F["Click Install WordPress"]
  F --> G["Success! Login with your credentials"]
  
  style F fill:#38bdf8,color:#0f172a
  style G fill:#38bdf8,color:#0f172a

That's it. You now have a working WordPress site on your local machine.

Method 2: MAMP (macOS)

MAMP is similar to XAMPP but designed specifically for macOS with a cleaner interface.

Step 1: Download and Install MAMP

Go to mamp.info and download the free version. The installer includes Apache, MySQL, PHP, and phpMyAdmin.

Step 2: Set Document Root

Open MAMP, click Preferences > Web Server, and set the document root to a folder like ~/Sites/wordpress. This is where WordPress files will live.

Step 3: Start Servers

Click Start Servers in MAMP. Apache and MySQL icons should turn green.

Step 4: Create Database and Install WordPress

Follow the same steps as XAMPP from Step 3 onward. The MySQL username is root and the password is also root by default in MAMP.

define( 'DB_NAME', 'wordpress' );
define( 'DB_USER', 'root' );
define( 'DB_PASSWORD', 'root' );
define( 'DB_HOST', 'localhost' );

Method 3: Docker (Modern & Clean)

Docker creates isolated containers for each service. No Apache or MySQL installs on your machine — everything runs in its own box.

Step 1: Install Docker Desktop

Download from docker.com and install. Docker works on Windows, macOS, and Linux.

Step 2: Create docker-compose.yml

Create a file called docker-compose.yml in a new folder:

services:
  db:
    image: mysql:8.0
    volumes:
      - db_data:/var/lib/mysql
    restart: unless-stopped
    environment:
      MYSQL_ROOT_PASSWORD: rootpassword
      MYSQL_DATABASE: wordpress
      MYSQL_USER: wordpress
      MYSQL_PASSWORD: wordpress

  wordpress:
    depends_on:
      - db
    image: wordpress:latest
    ports:
      - "8000:80"
    restart: unless-stopped
    environment:
      WORDPRESS_DB_HOST: db:3306
      WORDPRESS_DB_USER: wordpress
      WORDPRESS_DB_PASSWORD: wordpress
      WORDPRESS_DB_NAME: wordpress

volumes:
  db_data:

This creates two containers: one for MySQL 8.0 and one for the latest WordPress. The depends_on line tells Docker to start MySQL before WordPress — WordPress needs the database to be available.

Step 3: Start the Containers

docker compose up -d

The -d flag runs in detached mode (in the background).

Step 4: Complete the Install

Visit http://localhost:8000 and run the 5-minute install. Docker sets up wp-config.php automatically using the environment variables you defined.

Step 5: Stop When Done

docker compose down

This stops both containers. Run <a href="/devops/docker-compose/">Docker Compose</a> up -d again when you want to work. Your data persists in the Docker volume.

Understanding wp-config.php

The wp-config.php file is the heart of your WordPress installation. It controls database settings, security, debugging, and more.

// Database settings — tells WordPress where to find your data
define( 'DB_NAME', 'wordpress' );
define( 'DB_USER', 'root' );
define( 'DB_PASSWORD', '' );
define( 'DB_HOST', 'localhost' );

// Database charset — always use utf8mb4 for full Unicode support
define( 'DB_CHARSET', 'utf8mb4' );

// Security keys — generated per-site, encrypt user sessions
define( 'AUTH_KEY',         'random string here' );
define( 'SECURE_AUTH_KEY',  'random string here' );

// Table prefix — change from default 'wp_' for security
$table_prefix = 'wp_';

// Debug mode — enabled during development, disabled in production
define( 'WP_DEBUG', false );

WP_DEBUG is your most useful tool during development. Add this to your local wp-config.php:

define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false );

When enabled, WordPress logs all errors, warnings, and notices to /wp-content/debug.log. You can tail this file in real time to see what's happening:

tail -f wp-content/debug.log

Troubleshooting Common Installation Errors

Learning Path

flowchart LR
  A["What is WordPress?"] --> B["Local Installation
← You are here"]:::current
  B --> C["Admin Dashboard"]
  C --> D["Settings Guide"]
  D --> E["WordPress Hosting"]

  classDef current fill:#38bdf8,color:#0f172a,stroke-width:2px

Common Mistakes

1. Forgetting to start MySQL. Apache alone is not enough. WordPress needs both the web server (Apache) and the database server (MySQL). Check both are green in your control panel.

2. Using the default table prefix wp_ in production. Attackers target wp_ tables with SQL injection. Changing the prefix to something random adds a layer of protection. Do it before installing, never after.

3. Setting WP_DEBUG to true on a live site. This exposes error messages, file paths, and potentially database credentials to visitors. Only enable debugging on local installs.

4. Installing WordPress in the wrong directory. If your WordPress files are in htdocs directly (not in a subfolder), your site lives at http://localhost/ instead of http://localhost/wordpress/. Both work, but subfolders let you run multiple sites.

5. Not generating security salts. The default placeholder salts are the same for every installation. Without unique salts, your user sessions are easier to hijack. Always use the WordPress salt generator.

Practice Questions

1. What is the purpose of the wp-config.php file? Answer: wp-config.php is the central configuration file for WordPress. It stores database connection details, security keys, table prefix, and debugging settings. WordPress reads it on every page load.

2. Why should you use Docker for WordPress development? Answer: Docker creates isolated environments with no manual Apache/MySQL installation. You can spin up a fresh WordPress instance in seconds, test it, and destroy it without affecting your system. It guarantees the same environment across team members.

3. What does changing the table prefix from wp_ to something else do? Answer: It reduces the risk of SQL injection attacks that target WordPress's default table names. While not a complete security solution, it removes the low-hanging fruit for automated attacks.

4. Challenge: Set up three different WordPress local environments. Use XAMPP for one, Docker for another, and MAMP for the third. Install the same theme and plugin on all three. Note any differences in the experience — speed, file access, ease of database management. Write a short comparison of the three methods.

FAQ

Mini Project

Create a WordPress multisite playground:

1. Set up a Docker-based WordPress environment using the docker-compose.yml provided above.
2. Create a second WordPress site in XAMPP or MAMP (different folder, different database).
3. On the Docker site, install a block theme (e.g., Twenty Twenty-Four). On the XAMPP site, install a classic theme (e.g., Astra).
4. Configure both sites identically: same site title, same dummy content, different themes.
5. Compare the admin experience, the front-end output, and the file structure between the block theme and classic theme.

This project teaches you to manage multiple environments, a skill you'll use daily as a WordPress developer.

What's Next

Now that you have WordPress running locally, it's time to explore the admin dashboard:

Continue to Lesson 3: Admin Dashboard — Every menu, screen, and setting explained.

Related lessons:

• What is WordPress? — Start here if you skipped the introduction
• WordPress Settings Guide — Deep dive into all settings screens
• MySQL Database Guide — Understand the database behind WordPress