Docker Compose Up Command

Docker Compose Up Command

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.

The docker compose up command is the single most-used entry point for running multi-container applications defined in a compose.yaml file. Whether you are starting a local development environment or bringing a production stack online, understanding exactly what the docker compose up command does — and the flags that change its behavior — will save you from a lot of confusing debugging sessions later.

This guide walks through how the docker compose up command works, the flags you’ll use most often, common failure modes, and how it fits into a realistic DevOps workflow alongside related commands like build, down, and logs.

What the Docker Compose Up Command Actually Does

When you run docker compose up inside a directory containing a compose.yaml (or docker-compose.yml) file, Compose performs a sequence of steps:

1. Parses the compose file and resolves any .env variables referenced in it.
2. Creates a dedicated network for the project (unless one is already defined).
3. Creates named volumes that don’t already exist.
4. Builds images for any service with a build: directive, if they aren’t already built or --build is passed.
5. Creates containers for each service, respecting depends_on ordering.
6. Starts the containers and attaches your terminal to their combined log output.

This is different from docker compose start, which only starts containers that already exist — it does not create anything new. The docker compose up command is the one you reach for the first time you bring a stack online, and generally the one you keep using afterward too, since it’s idempotent: running it again with no changes simply leaves already-running containers alone.

# compose.yaml
services:
  web:
    image: nginx:latest
    ports:
      - "8080:80"
  api:
    build: ./api
    environment:
      - NODE_ENV=production
    depends_on:
      - db
  db:
    image: postgres:16
    volumes:
      - db_data:/var/lib/postgresql/data

volumes:
  db_data:

Running docker compose up against this file will build the api image, pull nginx and postgres if they aren’t cached locally, create the db_data volume, and start all three containers in dependency order.

Common Flags for the Docker Compose Up Command

Most day-to-day usage of the docker compose up command revolves around a small set of flags. Learning these well covers the vast majority of real workflows.

Detached Mode with -d

By default, the docker compose up command runs in the foreground and streams logs from every container to your terminal. Press Ctrl+C and Compose sends a stop signal to all containers. For anything long-running — a staging server, a background worker, a database — you almost always want detached mode instead:

docker compose up -d

This starts the containers and returns control of the terminal immediately. You can then check status with docker compose ps or tail logs on demand — see our complete guide to docker compose logs for filtering and following log output after the fact.

Rebuilding Images with --build

If you’ve changed a Dockerfile or the contents of a build context, Compose won’t automatically know to rebuild unless you tell it to:

docker compose up -d --build

This forces a rebuild of any service with a build: key before starting containers. It’s a common source of confusion — “I changed my code but the container still runs the old version” almost always means a missing --build flag. If you want more control over incremental vs. full rebuilds, our Docker Compose Rebuild guide covers the tradeoffs in depth.

Removing Orphan Containers

If you’ve renamed or removed a service from your compose file, old containers from a previous run can be left behind:

docker compose up -d --remove-orphans

This is good hygiene to include in CI/deploy scripts so stale containers never silently accumulate.

Docker Compose Up vs Related Commands

It helps to be explicit about what the docker compose up command does not do, since a few adjacent commands are frequently confused with it.

Up vs Start

docker compose start only starts containers that Compose already created. It does not read new configuration, build images, or create networks/volumes. docker compose up does all of that. If you’ve never run up for a given compose file, start will simply fail — there’s nothing to start yet.

Up vs Run

docker compose run is for one-off commands against a service’s image — for example, running a database migration or opening a shell — without affecting the rest of your stack’s running state. up is for bringing the full defined stack online. They solve different problems and shouldn’t be used interchangeably.

Up vs Down

docker compose down is effectively the inverse operation: it stops containers and removes them, along with the default network. It does not remove volumes unless you pass -v. If you’re troubleshooting a stack lifecycle issue, our Docker Compose Down guide is the natural companion reading to this one.

Environment Variables and the Docker Compose Up Command

A frequent source of “it works on my machine” bugs is environment variable resolution. The docker compose up command reads variables from three main places: a .env file in the project directory, variables exported in your shell, and environment:/env_file: entries inside the compose file itself.

Shell-exported variables generally take precedence over .env file values.

.env file values are used to interpolate ${VARIABLE} syntax inside compose.yaml itself, not just inside containers.

env_file: entries under a service inject variables into that specific container’s runtime environment, separate from interpolation.

Getting these three layers mixed up is one of the most common Compose mistakes. If you’re regularly hitting “variable not set” warnings when running the docker compose up command, our dedicated Docker Compose Env guide walks through the precedence rules and debugging techniques in more detail, and the Docker Compose Environment Variables guide covers the environment: key specifically.

Overriding Variables at Invocation Time

You can also pass variables inline for a single run of the docker compose up command:

API_KEY=test123 docker compose up -d

This is useful for CI pipelines or local overrides without editing a .env file, though for anything sensitive you should prefer Compose’s secrets support rather than inline environment variables — see the Docker Compose Secrets guide for that pattern.

Troubleshooting a Failed Docker Compose Up

When the docker compose up command fails, the error usually falls into one of a few categories:

Port conflicts — another process (or another Compose project) already binds the host port you specified.

Build failures — a Dockerfile step fails, often due to a missing file in the build context or a network issue during a package install.

Dependency ordering — a service starts before a dependency (like a database) is actually ready to accept connections, even though depends_on only waits for the container to start, not for the application inside it to be ready.

Volume permission issues — a mounted volume has ownership that doesn’t match the user the container process runs as.

Diagnosing with Logs

The first troubleshooting step after any failed docker compose up command should almost always be checking logs for the specific service that failed:

docker compose logs api --tail=100

Fixing Startup Ordering with Healthchecks

depends_on alone only guarantees container start order, not application readiness. To make a service genuinely wait for a database to be ready, pair depends_on with a condition: service_healthy and a healthcheck: block on the dependency:

services:
  db:
    image: postgres:16
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      timeout: 5s
      retries: 5
  api:
    build: ./api
    depends_on:
      db:
        condition: service_healthy

With this in place, the docker compose up command will hold off starting api until Postgres actually reports healthy, not just running.

Where to Run Docker Compose Up in Production

For local development, running the docker compose up command directly on your workstation is fine. For anything customer-facing, you’ll want a dedicated server rather than your laptop — a small unmanaged VPS is usually the simplest option for a single-host Compose deployment. Providers like DigitalOcean offer straightforward VPS instances that work well for this. If you’re new to running your own server rather than a managed platform, our Unmanaged VPS Hosting guide explains what you’re responsible for versus what the provider handles.

Once your compose file is running on a real host, keep in mind that docker compose up -d alone doesn’t restart automatically after a server reboot unless your services have a restart: policy set (e.g. restart: unless-stopped), and it doesn’t handle zero-downtime deploys — it will briefly stop and recreate containers whose configuration changed.

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

Does docker compose up rebuild images automatically?
No. It only builds an image if that image doesn’t exist yet for a service with a build: directive. If the image already exists — even if the underlying Dockerfile or source code has changed — Compose will reuse it unless you explicitly pass --build.

What’s the difference between docker compose up and docker compose up -d?
Without -d, Compose runs in the foreground and streams all container logs to your terminal until you stop it with Ctrl+C. With -d (detached), containers start in the background and control returns to your shell immediately.

Why does docker compose up say a port is already allocated?
Another container, another Compose project, or a non-Docker process on the host is already using that port. Stop the conflicting process, or change the host-side port mapping in your compose file (e.g. "8081:80" instead of "8080:80").

Can I run docker compose up for just one service?
Yes — pass the service name as an argument, e.g. docker compose up -d api. Compose will still start any services listed in depends_on for that service, but it won’t start unrelated services defined elsewhere in the file.

Conclusion

The docker compose up command is deceptively simple on the surface but has real nuance once you factor in build caching, environment variable precedence, and dependency readiness. Getting comfortable with its core flags — -d, --build, and --remove-orphans — along with understanding how it differs from start, run, and down, covers most of what you’ll need for day-to-day Compose work. For deeper dives into specific pieces of this workflow, see the official Docker Compose CLI reference and the broader Docker documentation.