Docker Compose Command: A Complete Reference Guide

Disclosure: This post contains one or more links to providers we have a real, registered affiliate/referral relationship with. We may earn a commission at no extra cost to you if you sign up through them.

Every Docker Compose workflow revolves around a handful of core commands, but understanding exactly what each docker compose command does — and when to use it — separates a smooth deployment from a debugging session at 2 AM. This guide walks through the essential docker compose command reference, from the basics of starting a stack to advanced troubleshooting patterns you’ll actually use in production.

Whether you’re running a single-container app or a multi-service stack with a database, cache, and reverse proxy, the same core set of commands applies. This article breaks down what each docker compose command does, common flags worth knowing, and practical patterns for day-to-day operations.

Understanding the Docker Compose Command Structure

Every docker compose command follows a consistent pattern: docker compose [OPTIONS] COMMAND [ARGS]. Modern Docker installations use the integrated docker compose (no hyphen) syntax rather than the older standalone docker-compose binary, though both accept largely the same subcommands and flags.

Compose reads its configuration from a compose.yaml (or docker-compose.yml) file in the current directory by default. You can point at a different file with the -f flag, which is useful when managing multiple environments (development, staging, production) from separate compose files.

The Anatomy of a Compose File

Before diving into commands, it helps to understand what Compose is actually acting on. A minimal file looks like this:

services:
  web:
    image: nginx:latest
    ports:
      - "8080:80"
    depends_on:
      - api
  api:
    build: ./api
    environment:
      - NODE_ENV=production

Each top-level entry under services becomes a target for docker compose commands — you can run docker compose up web to start just that service, or docker compose logs api to view logs for a single container without touching the rest of the stack.

Global Flags Available on Every Docker Compose Command

A few flags apply across almost every docker compose command and are worth memorizing:

-f, --file — specify an alternate compose file

-p, --project-name — override the default project name (normally the directory name)

--env-file — load environment variables from a specific file

-d, --detach — run containers in the background (used with up)

--profile — activate a named service profile

The Core Docker Compose Command for Starting Services

The docker compose up command is the one most people learn first, and for good reason — it builds images if needed, creates networks and volumes, and starts every service defined in the file.

docker compose up -d

Running this docker compose command with -d detaches the process so your terminal isn’t tied to container output. Without -d, Compose streams combined logs from every service directly to your terminal, which is genuinely useful the first time you bring up a new stack, since you can watch for startup errors in real time.

Rebuilding Images Before Starting

If you’ve changed a Dockerfile or application code that gets baked into an image, up alone won’t rebuild it — Compose reuses existing images unless told otherwise. Add the --build flag:

docker compose up -d --build

This is one of the most common docker compose command variations used in local development loops, since it guarantees you’re running the latest code rather than a stale cached layer. For a deeper look at rebuild behavior and caching pitfalls, see our guide on Docker Compose Rebuild.

Starting Only Specific Services

You rarely need to bring up an entire stack when debugging a single component:

docker compose up -d api

Compose will still start any services listed in depends_on for api, but it won’t touch unrelated services like a frontend container that isn’t in the dependency chain.

Stopping and Removing Containers with the Docker Compose Command Set

Two commands are frequently confused: docker compose stop and docker compose down. Knowing the difference matters, because one is reversible and the other is destructive to more than just containers.

docker compose stop halts running containers but leaves them, along with their networks and volumes, intact on disk. You can resume exactly where you left off with docker compose start.

docker compose down, by contrast, removes containers and networks entirely. By default it preserves named volumes, but adding -v deletes those too — meaning any database data stored in an unnamed or anonymous volume is gone permanently. We cover this distinction, along with safe shutdown patterns, in detail in Docker Compose Down: Full Guide to Stopping Stacks.

docker compose down --remove-orphans

The --remove-orphans flag is worth adding as a habit — it cleans up containers for services that used to exist in your compose file but have since been removed, preventing orphaned containers from lingering silently.

Inspecting Running Services

Viewing Logs with docker compose logs

Once services are running, docker compose logs is the fastest way to see what’s happening inside them without shelling into a container:

docker compose logs -f --tail=100 api

The -f flag follows the log stream live, and --tail limits initial output so you’re not scrolling through thousands of historical lines. For patterns around filtering, timestamping, and combining logs across services, see Docker Compose Logs: The Complete Debugging Guide.

Checking Service Status

docker compose ps lists containers managed by the current project, along with their state, exposed ports, and health status if a healthcheck is defined:

docker compose ps

This differs from plain docker ps in that it’s scoped to the current project directory’s compose file, so you only see containers relevant to the stack you’re working in — helpful when running multiple unrelated projects on the same host.

Executing Commands Inside a Running Container

Sometimes you need a shell or a one-off command inside a running service without stopping it. docker compose exec handles this:

docker compose exec api sh

This is different from docker compose run, which starts a brand-new container (useful for one-off tasks like running database migrations) rather than attaching to an already-running one.

Managing Configuration and Environment Variables

A large share of real-world Compose problems come from environment variable misconfiguration rather than the docker compose command itself failing. Compose merges variables from .env files, shell environment, and the environment: block in your service definition, and the precedence order isn’t always intuitive.

.env file values are substituted into the compose file at parse time

environment: block values set inside the running container

env_file: directive loads a file’s contents directly into the container

Shell-exported variables override .env file values during substitution

If a docker compose command isn’t picking up a variable you expect, running docker compose config prints the fully resolved configuration after all substitutions — an easy way to confirm what Compose actually sees. Our dedicated guide on Docker Compose Env: Manage Variables the Right Way walks through common pitfalls in more depth, and Docker Compose Environment Variables: Complete Guide covers additional substitution edge cases.

Validating Your Compose File

Before deploying, it’s worth running the validation docker compose command to catch syntax errors early:

docker compose config --quiet

This exits silently on success and prints a detailed error if the YAML is malformed or references an undefined variable, which is far faster than discovering the problem after up fails partway through starting your stack.

Practical Multi-Service Example

To tie these commands together, here’s a realistic compose file combining an application, a database, and a reverse proxy — the kind of stack you’d actually run in a homelab or small production deployment:

services:
  app:
    build: .
    depends_on:
      - db
    environment:
      - DATABASE_URL=postgres://user:pass@db:5432/appdb
    restart: unless-stopped

  db:
    image: postgres:16
    volumes:
      - db_data:/var/lib/postgresql/data
    restart: unless-stopped

volumes:
  db_data:

With this file in place, the typical docker compose command sequence for a deployment looks like:

docker compose config --quiet
docker compose up -d --build
docker compose ps
docker compose logs -f app

If you’re running Postgres specifically, our guide on Postgres Docker Compose: Full Setup Guide for 2026 covers volume persistence and backup strategies in more detail, and if you need a fast in-memory layer alongside it, Redis Docker Compose: The Complete Setup Guide is a useful companion reference.

Choosing Where to Run Your Docker Compose Stack

The docker compose command set works identically whether you’re running on a laptop or a cloud VPS, but production stacks benefit from predictable, dedicated resources rather than a shared or oversubscribed host. If you’re setting up a new server specifically to run Compose-managed services, a provider with straightforward block storage and predictable networking makes volume management and backups much less error-prone. DigitalOcean is a common choice for exactly this kind of small-to-medium Compose deployment, since droplets come with consistent CPU and disk performance that scales cleanly as you add services.

Recommended: Ready to put this into practice? DigitalOcean is a tool we use for exactly this, and we have a real, disclosed affiliate relationship with them.

FAQ

What’s the difference between docker compose up and docker compose start?
docker compose up creates containers, networks, and volumes if they don’t exist and then starts them — it’s the command you use for a fresh deployment or after changing the compose file. docker compose start only restarts containers that already exist and were previously stopped; it won’t pick up configuration changes.

Does the docker compose command work the same as docker-compose (with a hyphen)?
Largely yes. The docker compose command (integrated into the Docker CLI as a plugin) is the actively maintained version, while the standalone docker-compose Python-based binary is the legacy tool. Syntax and most flags are compatible, but new features land in the integrated version first, per the official Docker documentation.

How do I restart a single service without affecting the rest of the stack?
Use docker compose restart <service-name>. This stops and starts just that container, leaving other services running uninterrupted — useful after changing an environment variable that doesn’t require a rebuild.

Why does docker compose down sometimes remove data I wanted to keep?
This happens when the -v flag is included, which deletes named and anonymous volumes along with containers. If your database uses an anonymous volume rather than a named one declared under the top-level volumes: key, that data has no separate lifecycle from the container and is removed unless you explicitly avoid -v.

Conclusion

The docker compose command set is small enough to memorize but nuanced enough that misusing a flag — particularly around down -v or forgetting --build — can cause real problems. Sticking to a consistent workflow (config --quiet to validate, up -d --build to deploy, logs -f to verify, ps to check status) covers the vast majority of day-to-day operations. For orchestration needs beyond a single host, it’s also worth understanding how Compose concepts map onto larger systems like Kubernetes, since the service/network/volume model in Compose mirrors — at a smaller scale — the same primitives you’ll encounter there.