Overview of docker compose CLI
Important
From July 2023 Compose V1 stopped receiving updates. It's also no longer available in new releases of Docker Desktop.
Compose V2 is included with all currently supported versions of Docker Desktop. For more information, see Migrate to Compose V2.
Docker's documentation refers to and describes Compose V2 functionality.
This page provides the usage information for the docker compose
Command.
Important
The new Compose V2, which supports the
compose
command 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-compose
features and flags. You can run Compose V2 by replacing the hyphen (-
) with a space, usingdocker compose
, instead ofdocker-compose
.
For more information about Docker Compose V2 GA, see the blog post Announcing Compose V2 General Availabilityopen_in_new.
Command options overview and help
You can also see this information by running docker compose --help
from the
command line.
Usage: docker compose [OPTIONS] COMMAND
Define and run multi-container applications with Docker.
Options:
--ansi string Control when to print ANSI control characters ("never"|"always"|"auto") (default "auto")
--compatibility Run compose in backward compatibility mode
--env-file stringArray Specify an alternate environment file.
-f, --file stringArray Compose configuration files
--parallel int Control max parallelism, -1 for unlimited (default -1)
--profile stringArray Specify a profile to enable
--project-directory string Specify an alternate working directory
(default: the path of the, first specified, Compose file)
-p, --project-name string Project name
Commands:
build Build or rebuild services
config Parse, resolve and render compose file in canonical format
cp Copy files/folders between a service container and the local filesystem
create Creates containers for a service.
down Stop and remove containers, networks
events Receive real time events from containers.
exec Execute a command in a running container.
images List images used by the created containers
kill Force stop service containers.
logs View output from containers
ls List running compose projects
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 service containers
rm Removes stopped service containers
run Run a one-off command on 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
Run 'docker compose COMMAND --help' for more information on a command.
You can use Docker Compose binary, docker compose [-f <arg>...] [options] [COMMAND] [ARGS...]
, to build and manage multiple services in Docker containers.
Use -f to specify name and path of one or more Compose files
Use the -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
The docker-compose.yml
file might specify a webapp
service.
webapp:
image: examples/web
ports:
- "8000:8000"
volumes:
- "/data"
If the docker-compose.admin.yml
also specifies this same service, any matching
fields override the previous file. New values, add to the webapp
service
configuration.
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.
Use a -f
with -
(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.
The -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 docker-compose.yml
file.
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 sampleopen_in_new, and
have a 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
follows: 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
Use -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:
- The
-p
command line flag - The COMPOSE_PROJECT_NAME environment variable
- The top level
name:
variable from the config file (or the lastname:
from a series of config files specified using-f
) - The
basename
of the project directory containing the config file (or containing the first config file specified using-f
) - The
basename
of 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.
Use --profile to specify one or more active profiles
Calling docker compose --profile frontend up
will start the services with the
profile frontend
and services without specified profiles. You can also enable
multiple profiles, e.g. with docker compose --profile frontend --profile debug up
the profiles frontend
and 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 -f
and -p
flags.
For example, the
COMPOSE_FILE environment variable
relates to the -f
flag, and COMPOSE_PROJECT_NAME
environment variable relates to the -p
flag.
Also, you can set some of these variables in an environment file.