compose Documentation

1. Project Overview & Quickstart (docker/compose) Copy Chapter

File: README.md Copy Chapter

Table of Contents

• Docker Compose
• Where to get Docker Compose
  • Windows and macOS
  • Linux
• Quick Start
• Contributing
• Legacy

Docker Compose

Docker Compose is a tool for running multi-container applications on Docker
defined using the Compose file format.
A Compose file is used to define how one or more containers that make up
your application are configured.
Once you have a Compose file, you can create and start your application with a
single command: docker compose up.

Note: About Docker Swarm
Docker Swarm used to rely on the legacy compose file format but did not adopt the compose specification
so is missing some of the recent enhancements in the compose syntax. After
acquisition by Mirantis swarm isn't maintained by Docker Inc, and
as such some Docker Compose features aren't accessible to swarm users.

Where to get Docker Compose

Windows and macOS Copy Section

Docker Compose is included in
Docker Desktop
for Windows and macOS.

Linux Copy Section

You can download Docker Compose binaries from the
release page on this repository.

Rename the relevant binary for your OS to docker-compose and copy it to $HOME/.docker/cli-plugins

Or copy it into one of these folders to install it system-wide:

• /usr/local/lib/docker/cli-plugins OR /usr/local/libexec/docker/cli-plugins
• /usr/lib/docker/cli-plugins OR /usr/libexec/docker/cli-plugins

(might require making the downloaded file executable with chmod +x)

Quick Start Copy Chapter

Using Docker Compose is a three-step process:

1. Define your app's environment with a Dockerfile so it can be
   reproduced anywhere.
2. Define the services that make up your app in compose.yaml so
   they can be run together in an isolated environment.
3. Lastly, run docker compose up and Compose will start and run your entire
   app.

A Compose file looks like this:

services:
  web:
    build: .
    ports:
      - "5000:5000"
    volumes:
      - .:/code
  redis:
    image: redis

Contributing Copy Chapter

Want to help develop Docker Compose? Check out our
contributing documentation.

If you find an issue, please report it on the
issue tracker.

Legacy Copy Chapter

The Python version of Compose is available under the v1 branch.

File: docs/reference/compose.md Copy Chapter

docker compose

docker compose [-f <arg>...] [options] [COMMAND] [ARGS...]

Define and run multi-container applications with Docker

Subcommands Copy Section

Options Copy Section

Examples Copy Chapter

Use `-f` to specify the name and path of one or more Compose files Copy Section

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 compose.yaml -f compose.admin.yaml run backup_db

The compose.yaml file might specify a webapp service.

services:
  webapp:
    image: examples/web
    ports:
      - "8000:8000"
    volumes:
      - "/data"

If the compose.admin.yaml 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
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 compose.yaml or docker-compose.yaml 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 sample, and
have a 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

Using an OCI published artifact

You can use the -f flag with the oci:// prefix to reference a Compose file that has been published to an OCI registry.
This allows you to distribute and version your Compose configurations as OCI artifacts.

To use a Compose file from an OCI registry:

$ docker compose -f oci://registry.example.com/my-compose-project:latest up

You can also combine OCI artifacts with local files:

$ docker compose -f oci://registry.example.com/my-compose-project:v1.0 -f compose.override.yaml up

The OCI artifact must contain a valid Compose file. You can publish Compose files to an OCI registry using the
docker compose publish command.

Using a git repository

You can use the -f flag to reference a Compose file from a git repository. Compose supports various git URL formats:

Using HTTPS:

$ docker compose -f https://github.com/user/repo.git up

Using SSH:

$ docker compose -f [email protected]:user/repo.git up

You can specify a specific branch, tag, or commit:

$ docker compose -f https://github.com/user/repo.git@main up
$ docker compose -f https://github.com/user/[email protected] up
$ docker compose -f https://github.com/user/repo.git@abc123 up

You can also specify a subdirectory within the repository:

$ docker compose -f https://github.com/user/repo.git#main:path/to/compose.yaml up

When using git resources, Compose will clone the repository and use the specified Compose file. You can combine
git resources with local files:

$ docker compose -f https://github.com/user/repo.git -f compose.override.yaml up

Use `-p` to specify a project name Copy Section

Each configuration has a project name. Compose sets the project name using
the following mechanisms, in order of precedence:

• The -p command 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 -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.

$ 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

Use profiles to enable optional services Copy Section

Use --profile to specify one or more active profiles
Calling 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 frontend and debug is enabled.

Profiles can also be set by COMPOSE_PROFILES environment variable.

Configuring parallelism Copy Section

Use --parallel to specify the maximum level of parallelism for concurrent engine calls.
Calling 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.

Set up environment variables Copy Section

You can set environment variables for various docker compose options, including the -f, -p and --profiles flags.

Setting the COMPOSE_FILE environment variable is equivalent to passing the -f flag,
COMPOSE_PROJECT_NAME environment variable does the same as the -p flag,
COMPOSE_PROFILES environment variable is equivalent to the --profiles flag
and COMPOSE_PARALLEL_LIMIT does the same as the --parallel flag.

If flags are explicitly set on the command line, the associated environment variable is ignored.

Setting the COMPOSE_IGNORE_ORPHANS environment variable to true stops docker compose from detecting orphaned
containers for the project.

Setting the COMPOSE_MENU environment variable to false disables the helper menu when running docker compose up
in attached mode. Alternatively, you can also run docker compose up --menu=false to disable the helper menu.

Use Dry Run mode to test your command Copy Section

Use --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:

/* Detailed source-code truncated for AI context efficiency. */

From the example above, you can see that the first step is to pull the image defined by db service, then build the backend service.
Next, the containers are created. The db service is started, and the backend and 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 ps, ls, logs for example.

File: docs/reference/compose_alpha.md Copy Chapter

docker compose alpha

Experimental commands

Subcommands Copy Section

Options Copy Section

File: docs/reference/compose_alpha_dry-run.md Copy Chapter

docker compose alpha dry-run

Dry run command allows you to test a command without applying changes

File: docs/reference/compose_alpha_generate.md Copy Chapter

docker compose alpha generate

EXPERIMENTAL - Generate a Compose file from existing containers

Options Copy Section

File: docs/reference/compose_alpha_publish.md Copy Chapter

docker compose alpha publish

Publish compose application

Options Copy Section

File: docs/reference/compose_alpha_scale.md Copy Chapter

docker compose alpha scale

Scale services

Options Copy Section

File: docs/reference/compose_alpha_viz.md Copy Chapter

docker compose alpha viz

EXPERIMENTAL - Generate a graphviz graph from your compose file

Options Copy Section

File: docs/reference/compose_alpha_watch.md Copy Chapter

docker compose alpha watch

Watch build context for service and rebuild/refresh containers when files are updated

Options Copy Section

File: docs/reference/compose_attach.md Copy Chapter

docker compose attach

Attach local standard input, output, and error streams to a service's running container

Options Copy Section

2. Official Technical Reference & Guides (docker/docs) Copy Chapter

Docs @ Docker

Welcome to the Docker Documentation repository. This is the source for the Docker Docs Website.

Feel free to open pull requests or issues. Our docs are completely open source, and we deeply appreciate contributions from the Docker community!

Provide feedback Copy Chapter

We’d love to hear your feedback! To submit feedback:

• Click New issue on the docs repository, or
• Click Request changes in the right column of every page on
  docs.docker.com, or
• Click Give feedback on every page in the docs.

To get community support, use the Docker Community Slack. Personalized support is available
through the Docker Pro, Team, and Business subscriptions. See Docker
Pricing for details.

If you have an idea for a new feature or behavior change in a specific aspect of
Docker or have found a product bug, file an issue in the project's
repository.

Contribute to Docker docs Copy Chapter

We welcome contributions! To get started:

• CONTRIBUTING.md - Contribution workflow and setup
• STYLE.md - Writing style and content guidelines
• COMPONENTS.md - Component and shortcode usage

Copyright and license Copy Chapter

Copyright 2013-2026 Docker, Inc., released under the Apache 2.0 license.