Docker Compose Commands

Compose v2 is a Docker CLI plugin, so the command is docker compose with a space. The hyphenated docker-compose was v1, written in Python, and has been retired. Every command below is v2.

docker compose vs docker-compose

Most tutorials written before 2023 use the hyphen. Translating them is usually one keystroke, but a few things moved.

Two error messages come out of this split, and they mean opposite things. The third case is the one that confuses people most, because the old command works:

If scripts on the machine still call the old name, an alias covers interactive shells:

alias docker-compose='docker compose'

Aliases are not read by shell scripts, so anything running under sh script.sh or cron needs the command edited, or a two-line wrapper in /usr/local/bin/docker-compose.

Start and Stop

Run these from the directory that holds compose.yaml, or point at it with -f.

up -d is also how you apply changes: it compares the file against the running containers and recreates only the ones whose configuration changed. restart does not do that.

Status and Logs

Exec and Run

exec runs inside an existing container. run starts a new one from the service definition, which is the right tool for one-off jobs like migrations.

Without --rm, every run leaves a stopped container behind. docker compose ps -a shows them and docker compose rm clears them.

Build and Pull

Update a running stack to newer images:

docker compose pull
docker compose up -d

up -d recreates only the containers whose image changed. For services you build yourself, docker compose up -d --build does the same thing in one step. The Dockerfile generator is a quick way to get the build: side started.

watch needs a develop: block on the service, and it replaces the usual edit, rebuild, restart loop in development:

    develop:
      watch:
        - action: sync
          path: ./src
          target: /app/src
        - action: rebuild
          path: package.json

sync copies changed files into the running container, rebuild rebuilds the image and recreates the container, and sync+restart copies then restarts the process.

Files, Projects and Profiles

compose.override.yaml is loaded automatically alongside compose.yaml when you do not pass -f, which is the usual way to keep dev-only ports and bind mounts out of the main file. The same flags can live in the environment: COMPOSE_FILE=compose.yaml:compose.prod.yaml, COMPOSE_PROFILES=debug, COMPOSE_PROJECT_NAME=myproject.

Inside the file, include: pulls in another compose file as if it were part of this one, and x- keys hold YAML anchors you can reuse across services. Compose ignores any top-level key starting with x-, which is what makes them safe to define:

include:
  - ./monitoring/compose.yaml

x-logging: &default-logging
  driver: json-file
  options:
    max-size: "10m"
    max-file: "3"

services:
  web:
    image: nginx
    logging: *default-logging
  api:
    image: myapi
    logging: *default-logging

extends: on a service does the same for one service at a time, pulling its definition from another file and letting you override parts of it.

Environment Variables

Two different things share the name. ${VAR} in the file is substituted by Compose before anything starts, reading the shell environment and the project .env file. environment: and env_file: put variables inside the container. A variable in .env does not reach the container unless you pass it through.

When the same variable is set in more than one place, the order from strongest to weakest is run -e, then environment:, then env_file:, then ENV in the image's Dockerfile. warning: The "X" variable is not set. Defaulting to a blank string. means substitution found nothing, and docker compose config is the fastest way to see what it did use.

For passwords, secrets: keeps the value out of the environment and out of docker inspect. The file is mounted at /run/secrets/<name>, and most official images take a _FILE variant that reads it:

services:
  db:
    image: postgres:16
    environment:
      POSTGRES_PASSWORD_FILE: /run/secrets/db_password
    secrets:
      - db_password

secrets:
  db_password:
    file: ./db_password.txt

Validate and Clean Up

Found orphan containers on up is a warning, not an error: a service was renamed or removed from the file and its old container is still around. --remove-orphans on up or down clears it.

compose.yaml Keys

The keys you actually use, per service. Indentation is two spaces and matters.

Top-level volumes: and networks: declare the names the services refer to:

volumes:
  data:
networks:
  backend:

Services on the same project network reach each other by service name (db:5432), which is why DB_HOST=db works. Compose creates a default network per project, so you only need networks: when you want to split services up.

Volumes

Named volumes have to be declared at the top level before a service can use one:

volumes:
  data:
  cache:
    external: true

external: true means Compose will use a volume you created yourself with docker volume create and will not remove it, even on down -v. Everything else gets the project name as a prefix, so data in project myapp is really myapp_data and lives under /var/lib/docker/volumes/myapp_data/_data on a Linux host. docker volume ls lists them, docker volume inspect myapp_data gives the path, and docker compose config --volumes prints the names the file declares.

Networks

Compose puts every service on a network called <project>_default and registers each service name in its DNS, so db resolves from any other container in the project. Nothing else is needed for containers to talk to each other.

To join a network created outside the project, for example one shared with a reverse proxy, declare it as external:

services:
  web:
    networks:
      - proxy
      - default

networks:
  proxy:
    external: true

could not resolve host or a connection refused between two containers is almost always one of three things: the services are not on a shared network, you used the published host port instead of the container port (db:5432, not db:15432), or you used localhost, which inside a container means that container. docker compose exec web getent hosts db settles it in one line. This is how Traefik and Caddy reach app containers: the proxy joins the same network and talks to the service name.

Restart and Autostart

For a stack that should come back after a reboot, restart: unless-stopped on every service plus sudo systemctl enable docker is enough. When the stack needs a defined boot order, a mounted disk, or a wait for the network, a unit file is better:

[Unit]
Description=myapp compose stack
Requires=docker.service
After=docker.service network-online.target

[Service]
Type=oneshot
RemainAfterExit=yes
WorkingDirectory=/srv/myapp
ExecStart=/usr/bin/docker compose up -d
ExecStop=/usr/bin/docker compose down

[Install]
WantedBy=multi-user.target

systemctl enable --now myapp then owns the stack. The systemd unit generator writes files like this, and the systemctl commands sheet covers the rest. A container stuck in a restart loop is a different problem; see Docker container keeps restarting.

Limits, Users and Devices

deploy.resources is honoured by plain docker compose, not only by Swarm. GPUs go under reservations:

    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]

Example compose.yaml

A web app built from the local Dockerfile, a Postgres database with a healthcheck, and a named volume for its data:

services:
  web:
    build: .
    image: myapp:latest
    ports:
      - "8080:3000"
    env_file: .env
    environment:
      DB_HOST: db
      NODE_ENV: production
    depends_on:
      db:
        condition: service_healthy
    restart: unless-stopped

  db:
    image: postgres:16
    volumes:
      - data:/var/lib/postgresql/data
    environment:
      POSTGRES_PASSWORD: ${DB_PASSWORD:-changeme}
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 10s
    restart: unless-stopped

volumes:
  data:

${DB_PASSWORD:-changeme} reads DB_PASSWORD from the shell or the project .env file and falls back to changeme. The Docker Compose generator builds files like this for common stacks.

Healthcheck and depends_on

depends_on alone only orders startup: the db container starts first, but Postgres may still be initialising when web connects. A healthcheck plus condition: service_healthy makes Compose wait.

The check runs inside the container, so curl or pg_isready has to exist in that image. Alpine images often lack curl; wget -qO- http://localhost:3000/health usually works instead. docker compose ps shows (healthy) or (unhealthy) next to the state, and docker inspect -f '{{json .State.Health}}' container shows the last few results.

command vs entrypoint

The string form (command: npm start) is split on spaces by Compose without a shell, so quotes inside it are kept literally and && is passed as an argument. When in doubt, use the list form and name sh -c explicitly. A multi-line script can go under a folded block scalar:

    command: >
      sh -c "npm run migrate &&
             npm run seed &&
             npm start"

Install and Version

Compose v2 is a plugin, so it installs next to the Docker CLI rather than on its own.

The distribution package called docker-compose is v1 on older Debian and Ubuntu releases, which is why the plugin package has a different name and comes from Docker's repository, not the distribution's. To install by hand:

mkdir -p ~/.docker/cli-plugins
curl -SL https://github.com/docker/compose/releases/latest/download/docker-compose-linux-x86_64 \
  -o ~/.docker/cli-plugins/docker-compose
chmod +x ~/.docker/cli-plugins/docker-compose
docker compose version

Use /usr/local/lib/docker/cli-plugins/ instead of ~/.docker/cli-plugins/ to install it for every user. If every command needs sudo, add yourself to the docker group with sudo usermod -aG docker $USER and log out and back in; see Cannot connect to the Docker daemon when it still fails.

Gotchas

• docker compose restart does not read the file again. After editing compose.yaml, run docker compose up -d; it recreates only what changed.
• stop and down are not the same. stop keeps the containers so start resumes them with their writable layer intact; down deletes them and the project network, and up builds new ones. Named volumes outlive both.
• down -v deletes every named volume declared in the file, including the database. down alone keeps them.
• the attribute "version" is obsolete is v2 telling you to delete the version: "3.8" line at the top of the file. It has no effect and never did in v2.
• additional property X is not allowed is a schema error: a misspelled key, or a service key written at the top level (or the other way round). docker compose config -q points at the line.
• depends_on without a condition only orders container starts. Add a healthcheck and condition: service_healthy when the app crashes on boot because the database is not ready.
• Ports in YAML must be quoted ("8080:80"); 22:22 unquoted is parsed as a base-60 number by some YAML parsers and becomes garbage.
• .env in the project directory feeds ${VAR} substitution in the file. env_file: feeds the container. They are different files with different jobs, and a variable in .env does not reach the container unless you also pass it through environment: or env_file:.
• Services started with --profile need the same --profile on down, or their containers are left running.
• Error response from daemon: ... port is already allocated on up means another container, or a process on the host, holds that port. docker ps and ss -tlnp find it; see Error response from daemon for the other variants.
• Bare docker commands work on Compose containers too: docker logs myproject-web-1, docker exec -it myproject-web-1 sh. The docker commands sheet covers them.