Overview of docker compose CLI
From the end of June 2023 Compose V1 won’t be supported anymore and will be removed from all Docker Desktop versions.
Make sure you switch to Compose V2 with the
docker composeCLI plugin or by activating the Use Docker Compose V2 setting in Docker Desktop. For more information, see the Evolution of Compose
This page provides the usage information for the
docker compose Command.
The new Compose V2, which supports the
composecommand as part of the Docker CLI, is now available.
Compose V2 integrates compose functions into the Docker platform, continuing to support most of the previous
docker-composefeatures and flags. You can run Compose V2 by replacing the hyphen (
-) with a space, using
docker compose, instead of
For more information about Docker Compose V2 GA, see the blog post Announcing Compose V2 General Availability.
Command options overview and help
You can also see this information by running
docker compose --help from the
Define and run multi-container applications with Docker. Usage: docker compose [-f <arg>...] [--profile <name>...] [options] [COMMAND] [ARGS...] docker compose -h|--help Options: -f, --file FILE Specify an alternate compose file (default: docker-compose.yml) -p, --project-name NAME Specify an alternate project name (default: directory name) --profile NAME Specify a profile to enable --verbose Show more output --log-level LEVEL DEPRECATED and not working from 2.0 - Set log level (DEBUG, INFO, WARNING, ERROR, CRITICAL) --no-ansi Do not print ANSI control characters -v, --version Print version and exit -H, --host HOST Daemon socket to connect to --tls Use TLS; implied by --tlsverify --tlscacert CA_PATH Trust certs signed only by this CA --tlscert CLIENT_CERT_PATH Path to TLS certificate file --tlskey TLS_KEY_PATH Path to TLS key file --tlsverify Use TLS and verify the remote --skip-hostname-check Don't check the daemon's hostname against the name specified in the client certificate --project-directory PATH Specify an alternate working directory (default: the path of the Compose file) --compatibility If set, Compose will attempt to convert deploy keys in v3 files to their non-Swarm equivalent Commands: build Build or rebuild services bundle Generate a Docker bundle from the Compose file config Validate and view the Compose file create Create services down Stop and remove containers, networks, images, and volumes events Receive real time events from containers exec Execute a command in a running container help Get help on a command images List images kill Kill containers logs View output from containers pause Pause services port Print the public port for a port binding ps List containers pull Pull service images push Push service images restart Restart services rm Remove stopped containers run Run a one-off command scale Set number of containers for a service start Start services stop Stop services top Display the running processes unpause Unpause services up Create and start containers version Show the Docker Compose version information
You can use Docker Compose binary,
docker compose [-f <arg>...] [options]
[COMMAND] [ARGS...], to build and manage multiple services in Docker containers.
-f to specify name and path of one or more Compose files
-f flag to specify the location of a Compose configuration file.
Specifying multiple Compose files
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
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: build: . environment: - DEBUG=1
When you use multiple Compose files, all paths in the files are relative to the
first configuration file specified with
-f. You can use the
--project-directory option to override this base path.
- (dash) as the filename to read the configuration from
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
docker-compose.yml and a
docker-compose.override.yml file. You must supply
at least the
docker-compose.yml file. If both files are present on the same
directory level, Compose combines the two files into a single configuration.
The configuration in the
docker-compose.override.yml file is applied over and
in addition to the values in the
Specifying a path to a single Compose file
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
docker-compose.yml 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
docker compose -f ~/sandbox/rails/docker-compose.yml pull db
Here’s the full example:
$ docker compose -f ~/sandbox/rails/docker-compose.yml pull db Pulling db (postgres:latest)... latest: Pulling from library/postgres ef0380f84d05: Pull complete 50cf91dc1db8: Pull complete d3add4cd115c: Pull complete 467830d8a616: Pull complete 089b9db7dc57: Pull complete 6fba0a36935c: Pull complete 81ef0e73c953: Pull complete 338a6c4894dc: Pull complete 15853f32f67c: Pull complete 044c83d92898: Pull complete 17301519f133: Pull complete dcca70822752: Pull complete cecf11b8ccf3: Pull complete Digest: sha256:1364924c753d5ff7e2260cd34dc4ba05ebd40ee8193391220be0f9901d4e1651 Status: Downloaded newer image for postgres:latest
-p to specify a project name
Each configuration has a project name which Compose can set in different ways. The level of precedence (from highest to lowest) for each method is as follows:
-pcommand line flag
- The COMPOSE_PROJECT_NAME environment variable
- 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
basename of the project directory or current directory violates this
constraint, you must use one of the other mechanisms.
--profile to specify one or more active profiles
docker compose --profile frontend up will start the services with the
frontend and services without specified profiles. You can also enable
multiple profiles, e.g. with
docker compose --profile frontend --profile debug up
debug will be enabled.
See also Using profiles with Compose and the
COMPOSE_PROFILES environment variable.
Set up environment variables
You can set environment variables for various
docker compose options, including the
For example, the COMPOSE_FILE environment variable
relates to the
-f flag, and
environment variable relates to the
Also, you can set some of these variables in an environment file.