You can use the compose subcommand,
docker compose [-f <arg>...] [options] [COMMAND] [ARGS...], to build and manage
multiple services in Docker containers.
-f flag to specify the location of a Compose configuration file.
You can supply multiple
-f configuration files. When you supply multiple files, Compose combines them into a single
configuration. Compose builds the configuration in the order you supply the files. Subsequent files override and add
to their predecessors.
For example, consider this command line:
$ docker compose -f docker-compose.yml -f docker-compose.admin.yml run backup_db
docker-compose.yml file might specify a
services: webapp: image: examples/web ports: - "8000:8000" volumes: - "/data"
docker-compose.admin.yml also specifies this same service, any matching fields override the previous file.
New values, add to the
webapp service configuration.
services: webapp: build: . environment: - DEBUG=1
When you use multiple Compose files, all paths in the files are relative to the first configuration file specified
-f. You can use the
--project-directory option to override this base path.
- (dash) as the filename to read the configuration from stdin. When stdin is used all paths in the
configuration are relative to the current working directory.
-f flag is optional. If you don’t provide this flag on the command line, Compose traverses the working directory
and its parent directories looking for a
You can use the
-f flag to specify a path to a Compose file that is not located in the current directory, either
from the command line or by setting up a
COMPOSE_FILE environment variable in your shell or in an environment file.
For an example of using the
-f option at the command line, suppose you are running the Compose Rails sample, and
compose.yaml file in a directory called
sandbox/rails. You can use a command like
docker compose pull to
get the postgres image for the db service from anywhere by using the
-f flag as follows:
$ docker compose -f ~/sandbox/rails/compose.yaml pull db
Each configuration has a project name. Compose sets the project name using the following mechanisms, in order of precedence:
-pcommand line flag
- The top level
name:variable from the config file (or the last
name:from a series of config files specified using
basenameof the project directory containing the config file (or containing the first config file specified using
basenameof the current directory if no config file is specified Project names must contain only lowercase letters, decimal digits, dashes, and underscores, and must begin with a lowercase letter or decimal digit. If the
basenameof the project directory or current directory violates this constraint, you must use one of the other mechanisms.
$ docker compose -p my_project ps -a NAME SERVICE STATUS PORTS my_project_demo_1 demo running $ docker compose -p my_project logs demo_1 | PING localhost (127.0.0.1): 56 data bytes demo_1 | 64 bytes from 127.0.0.1: seq=0 ttl=64 time=0.095 ms
--profile to specify one or more active profiles
docker compose --profile frontend up starts the services with the profile
frontend and services
without any specified profiles.
You can also enable multiple profiles, e.g. with
docker compose --profile frontend --profile debug up the profiles
debug is enabled.
Profiles can also be set by
COMPOSE_PROFILES environment variable.
--parallel to specify the maximum level of parallelism for concurrent engine calls.
docker compose --parallel 1 pull pulls the pullable images defined in the Compose file
one at a time. This can also be used to control build concurrency.
Parallelism can also be set by the
COMPOSE_PARALLEL_LIMIT environment variable.
You can set environment variables for various docker compose options, including the
COMPOSE_FILE environment variable is equivalent to passing the
COMPOSE_PROJECT_NAME environment variable does the same as the
COMPOSE_PROFILES environment variable is equivalent to the
COMPOSE_PARALLEL_LIMIT does the same as the
If flags are explicitly set on the command line, the associated environment variable is ignored.
COMPOSE_IGNORE_ORPHANS environment variable to
true stops docker compose from detecting orphaned
containers for the project.
--dry-run flag to test a command without changing your application stack state.
Dry Run mode shows you all the steps Compose applies when executing a command, for example:
$ docker compose --dry-run up --build -d [+] Pulling 1/1 ✔ DRY-RUN MODE - db Pulled 0.9s [+] Running 10/8 ✔ DRY-RUN MODE - build service backend 0.0s ✔ DRY-RUN MODE - ==> ==> writing image dryRun-754a08ddf8bcb1cf22f310f09206dd783d42f7dd 0.0s ✔ DRY-RUN MODE - ==> ==> naming to nginx-golang-mysql-backend 0.0s ✔ DRY-RUN MODE - Network nginx-golang-mysql_default Created 0.0s ✔ DRY-RUN MODE - Container nginx-golang-mysql-db-1 Created 0.0s ✔ DRY-RUN MODE - Container nginx-golang-mysql-backend-1 Created 0.0s ✔ DRY-RUN MODE - Container nginx-golang-mysql-proxy-1 Created 0.0s ✔ DRY-RUN MODE - Container nginx-golang-mysql-db-1 Healthy 0.5s ✔ DRY-RUN MODE - Container nginx-golang-mysql-backend-1 Started 0.0s ✔ DRY-RUN MODE - Container nginx-golang-mysql-proxy-1 Started Started
From the example above, you can see that the first step is to pull the image defined by
db service, then build the
Next, the containers are created. The
db service is started, and the
proxy wait until the
db service is healthy before starting.
Dry Run mode works with almost all commands. You cannot use Dry Run mode with a command that doesn't change the state of a Compose stack such as
logs for example.
|Control when to print ANSI control characters ("never"|"always"|"auto")|
|Run compose in backward compatibility mode|
|Execute command in dry run mode|
|Specify an alternate environment file.|
|Compose configuration files|
|Do not print ANSI control characters (DEPRECATED)|
|Control max parallelism, -1 for unlimited|
|Specify a profile to enable|
|Set type of progress output (auto, tty, plain, quiet)|
|Specify an alternate working directory (default: the path of the, first specified, Compose file)|
|Show more output|
|Show the Docker Compose version information|
|DEPRECATED! USE --project-directory INSTEAD. Specify an alternate working directory (default: the path of the, first specified, Compose file)|