Getting Started With Docker Compose: A Guide With Examples

Docker Compose is a tool for defining and running multi-container Docker applications. When using Docker, running and managing multiple containers becomes cumbersome. Docker Compose solves this problem.

You use YAML to configure your application services. The file is conventionally named docker-compose.yml (or compose.yaml), but you can give it a different name and point to it explicitly. Compose provides the docker compose command to manage the containers defined in that file.

Also check

Installing Docker Compose

You can run Compose on macOS, Windows, and 64-bit Linux.

Docker Compose relies on Docker Engine, so make sure you have Docker Engine installed before proceeding.

Modern Docker Compose (v2) ships as a plugin for the Docker CLI and is invoked as docker compose (two words). If you installed Docker Engine or Docker Desktop recently, it is already included. On Debian/Ubuntu you can install or update it explicitly from Docker’s repository:

1
2
sudo apt-get update
sudo apt-get install docker-compose-plugin

On RPM-based distributions (CentOS, Fedora, RHEL):

1
sudo yum install docker-compose-plugin

Verify the installation:

1
docker compose version

Older guides install Compose with pip install docker-compose. That is Compose v1 (the Python docker-compose command), which reached end of life in 2024 and was removed from Docker’s official images in 2025. Use the docker compose v2 plugin shown above instead — the sub-commands are the same, you just replace the hyphen in docker-compose with a space (docker compose).

WordPress MySQL example

You can use Docker Compose to easily run WordPress in an isolated environment built with Docker containers. This quick-start demonstrates how to use Compose to set up and run WordPress.

Sample docker-compose.yaml file:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
services:
  db:
    image: mysql:8.4
    volumes:
      - ~/apps/wordpress/db:/var/lib/mysql
    environment:
      MYSQL_ROOT_PASSWORD: toor
      MYSQL_DATABASE: wordpress
      MYSQL_USER: wordpress
      MYSQL_PASSWORD: wordpress

  wordpress:
    depends_on:
      - db
    image: wordpress:latest
    volumes:
      - ~/apps/wordpress/site:/var/www/html
    ports:
      - 8000:80
    environment:
      WORDPRESS_DB_HOST: db:3306
      WORDPRESS_DB_USER: wordpress
      WORDPRESS_DB_PASSWORD: wordpress
      WORDPRESS_DB_NAME: wordpress

volumes:
  db_data: {}
  wordpress_data: {}

The top-level version key (for example version: "3.9") that older Compose files start with is obsolete in Compose v2 — it is ignored and only prints a warning, so it has been dropped here. mysql:8.4 is the current MySQL LTS release (MySQL 8.0 reached end of life in April 2026), and wordpress:latest always pulls the newest release — pin a specific tag such as wordpress:6.8 if you need reproducible builds.

Running the project:

1
docker compose up -d

Open a shell in the running WordPress container:

1
docker compose exec wordpress sh

Use http://localhost as the IP address, and open http://localhost:8000 in a web browser.

If you need elevated privileges to bring up the containers, you can set privileged and user on a service:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
services:
  db:
    image: mysql:8.4
    volumes:
      - ~/apps/wordpress/db:/var/lib/mysql
    privileged: true
    user: root
    environment:
      MYSQL_ROOT_PASSWORD: toor
      MYSQL_DATABASE: wordpress
      MYSQL_USER: wordpress
      MYSQL_PASSWORD: wordpress

Shutdown and cleanup

The command docker compose down removes the containers and default network, but preserves your WordPress database (the named volume).

To also remove the database volume, add the --volumes flag:

1
docker compose down --volumes