Docker Compose Cheat Sheet: Command Reference
When working with Docker Compose daily, it's easy to forget the exact options or syntax and end up looking things up again. This article organizes the most commonly used Docker Compose commands by what you're trying to do, so you can quickly find what you need.
docker compose
Description
Build
Builds images for your services using the Dockerfile defined in the build section of compose.yml. You can specify a service name to build only that service.
docker compose build
docker compose build <service>
Rebuilds images without using the cache. Use this when you've updated dependencies or the build gets stuck on a cached layer and doesn't behave as expected.
docker compose build --no-cache
Pulls images defined in compose.yml from a registry such as Docker Hub. Useful for pre-fetching images for services that don't require a build step.
docker compose pull
Start
Creates and starts containers. Add -d to run them in the background (detached mode). You can specify a service name to start only that service — any services it depends on will also be started automatically.
docker compose up
docker compose up -d
docker compose up -d <service>
Builds images before starting containers. Use this when you want to apply code changes.
docker compose up --build -d
Starts stopped containers. If you stopped them with stop without running docker compose down, use this to resume them.
docker compose start
Restarts containers. Useful when you've updated a config file or a container becomes unresponsive. You can also restart a specific service only.
docker compose restart
docker compose restart <service>
Environment Variables
Docker Compose automatically loads the .env file in your project root. You can reference variables inside compose.yml as ${VARIABLE_NAME}. This is useful for injecting environment-specific values like port numbers and database names from outside the config.
# Example .env file
DB_NAME=mydb
DB_PORT=5432
To use a file other than .env, pass the --env-file option. This makes it easy to switch between different files for development, staging, and production.
docker compose --env-file .env.production up -d
To override specific environment variables when running a one-off container with docker compose run, use the -e option.
docker compose run -e LOG_LEVEL=debug <service> <command>
To verify that environment variables are loaded correctly, display the resolved compose.yml with docker compose config, or run the env command inside the container.
docker compose config
docker compose exec <service> env
Scaling
To run multiple containers for a service, use the --scale option. This is handy when you want to spin up multiple containers for load balancer testing or load testing.
docker compose up -d --scale <service>=3
Re-running up with a different scale count updates the number of running containers. Use this to dynamically adjust the number of instances.
docker compose up -d --scale <service>=1
To avoid port conflicts when scaling out, don't pin the host-side port in compose.yml — specify only the container-side port and let Docker assign host ports automatically.
# Don't fix the host-side port
ports:
- "8080"
To check how many containers are running, use docker compose ps. This lets you quickly confirm that the scale count has taken effect.
docker compose ps
Network
Docker Compose automatically creates a network prefixed with the project name. All services defined in the same compose.yml can reach each other by container name (service name) within this network.
To connect services across multiple compose.yml files, use an external network. Create the network in advance with docker network create, then reference it in the networks section of compose.yml with external: true.
networks:
shared-net:
external: true
Use docker network ls to list all networks. This shows both the auto-created network prefixed with the project name and any external networks.
docker network ls
Use docker network inspect to see detailed information about a specific network, including connected containers and settings. Useful for debugging name resolution between containers.
docker network inspect <network>
docker compose down removes the network by default, but external networks (external: true) are not removed. This prevents accidentally deleting a network shared across projects.
Container Status
Shows the status of each service (running, stopped, etc.). Displays container names, statuses, and exposed ports in a list, making it easy to verify startup. Add --all to include stopped containers as well.
docker compose ps
docker compose ps --all
Shows the processes running inside service containers. Use this when you want to see what's happening inside a container or check for any unexpected processes.
docker compose top
Displays logs. Use -f to follow logs in real time, and --tail to limit the number of lines shown. Omit the service name to see logs from all services, or specify one to filter to a specific service.
docker compose logs
docker compose logs -f
docker compose logs --tail 100 <service>
Container Operations
Opens a shell inside a running service container. If the container doesn't have bash (e.g., Alpine Linux-based images), use sh instead.
docker compose exec -it <service> bash
docker compose exec -it <service> sh
Runs a command in a one-off container without starting the service. Great for running database migrations or seed scripts. Adding --rm removes the container automatically after it exits.
docker compose run --rm <service> <command>
Copies a file from the host into a container. Useful for pushing in configuration files.
docker compose cp <host-path> <service>:<container-path>
Copies a file from a container to the host. Useful for pulling out log files or configuration files.
docker compose cp <service>:<container-path> <host-path>
Config
Displays the resolved compose.yml with all variables expanded. Useful for verifying that environment variables are being applied correctly.
docker compose config
Lists the names of all services defined in compose.yml. Handy when you need to retrieve service names in a script.
docker compose config --services
Troubleshooting
If a container exits immediately on startup and you can't get inside it, start a new container interactively with docker compose run. This is also useful when you want to manually reproduce the steps that caused the error.
docker compose run --rm <service> bash
Tracks container events (start, stop, crash, etc.) in real time. Useful for detecting crash-looping services. Add --json to output events in JSON format for scripting.
docker compose events
docker compose events --json
To check only recent logs, use --since to filter by time. This is useful when a long-running service has accumulated a large volume of logs.
docker compose logs --since 1h <service>
Checks which host port corresponds to a container-side port. Also useful when running scaled containers to find out which host port each instance was assigned.
docker compose port <service> <container-port>
Stop / Remove
Stops running containers without removing them. Containers are preserved and can be reused the next time you run up.
docker compose stop
Stops and removes containers along with their network. Add --rmi all to also remove images.
docker compose down
docker compose down --rmi all
Also removes volumes. Note that any data stored in the volumes will be lost. Use this when you want to reset your development environment to a clean state.
docker compose down -v
Quick Reference
A summary of commonly used commands and their syntax. Use this as a quick lookup when you forget the argument order.
| Command | Description |
|---|---|
docker compose up [service] | Create and start containers |
docker compose down | Stop and remove containers |
docker compose start [service] | Start stopped containers |
docker compose stop [service] | Stop containers |
docker compose restart [service] | Restart containers |
docker compose build [service] | Build images |
docker compose pull [service] | Pull images |
docker compose exec [service] | Run a command in a running container |
docker compose run [service] | Run a command in a one-off container |
docker compose logs [service] | Show logs |
docker compose ps [service] | Show service status |
docker compose top [service] | Show running processes |
docker compose cp [src] | Copy files between host and container |
docker compose config | Show resolved compose.yml |
docker compose events | Track events in real time |
Summary
- The basic workflow is: build → start → check status
- Manage environment variables in a dedicated file rather than hardcoding them in your config
- Rebuild images whenever you update code or dependencies
- Use an external network when you need services across multiple compose files to communicate
- When something goes wrong, check the logs and open a shell inside the container to investigate
- To reset your data, remove everything including volumes