Docker Compose Up: What `-d` Does and How to Check Your Stack

docker compose up -d starts the services in your Compose file and gives your terminal back. The containers keep running in the background, but their output no longer streams to your shell.

That difference is easy to miss: -d changes how you interact with the command, not what a Compose stack is made of. Here’s a practical way to start services, check what happened, and decide when you actually need a rebuild or a fresh container.

Foreground or detached?

Run up without -d when you want to watch startup output directly:

docker compose up

Compose stays attached to the container output. This is handy during development, but the terminal remains occupied until you stop the attached process.

Add -d (short for --detach) when you want the services to run in the background:

docker compose up -d

The command returns to your shell after starting the services. To see what the services are doing, check their status or follow their logs:

docker compose ps
docker compose logs -f

You can follow just one service’s output by naming it:

docker compose logs -f web

Detached does not mean “guaranteed to stay healthy.” A container can exit or restart after Compose returns, so check ps and logs when a service isn’t responding as expected. For more ways to follow recent and live Docker logs, including limiting the output to recent lines, use the docker logs options that fit your workflow.

What up does—and what it doesn’t

Compose reads the project’s Compose file, creates and starts the defined services, and makes required images, networks, and volumes available. You can start the whole project or name a service:

# Start all services in the background
docker compose up -d

# Start web and any required dependencies
docker compose up -d web

If you changed a Dockerfile or build context and want Compose to build before starting, be explicit:

docker compose up -d --build

A plain docker compose up -d does not force an existing image to rebuild. Compose may build an image when one is needed and unavailable, but don’t assume that editing a Dockerfile automatically means the image was rebuilt. Also, changing code in a bind-mounted directory does not by itself make Compose recreate the container; what happens next depends on how the project is configured.

Running up again is not the same as starting from scratch. Compose checks the existing containers against the current configuration and image. It generally leaves unchanged services alone and recreates affected containers when needed. Mounted volumes are preserved when containers are recreated.

If you need every container recreated, use --force-recreate. If you want to avoid recreation, use --no-recreate:

docker compose up -d --force-recreate
docker compose up -d --no-recreate

Use those flags for a specific reason: forcing recreation can interrupt services, while preventing it can leave containers running with configuration you meant to change.

Choose a stop command deliberately

There’s a meaningful difference between stopping containers and removing them:

# Stop containers but leave them in place
docker compose stop

# Stop and remove containers and the Compose network
docker compose down

Use stop when you expect to start the same containers again. Use down when you want to remove the containers and network created for the project. If you’re unsure what cleanup a command will perform, check what docker compose down removes before adding extra cleanup options.

When Compose can’t find your project

By default, Compose looks for a supported Compose file in the current directory. If you run the command elsewhere, you may see an error such as no configuration file provided: not found. Change to the project directory or pass the file explicitly:

cd /path/to/project
docker compose up -d

Or specify the file directly:

docker compose -f /path/to/compose.yaml up -d

Put -f before up. You can also start a named service with a specific file:

docker compose -f compose.prod.yml up -d web

docker compose or docker-compose?

The spaced command, docker compose, uses the Compose V2 CLI plugin. The hyphenated docker-compose command is the older standalone Compose V1 form. Which one works depends on what’s installed in your environment; don’t assume both commands are available.

If Compose isn’t recognized, check which version your Docker CLI can find:

docker --version
docker compose version
docker-compose --version

Use the command supported by that installation. For current Compose workflows, the spaced docker compose form is the one to use when the plugin is installed.

A quick routine after starting a stack

For a background start, then a basic health check, this is a useful sequence:

docker compose up -d
docker compose ps
docker compose logs -f

Use ps to see whether containers are running, restarting, or exited. Use logs to investigate startup errors or a service that isn’t behaving as expected. Add --build when you need to rebuild an image, and choose stop or down based on whether you want to keep the containers around.

I originally published a more detailed version of this guide on the SSHFlow blog.

I'm also building SSHFlow — an SSH client where every server gets its own workspace for terminals, SFTP, code, and databases.