## 1. Project Overview & Quickstart (docker/compose)

## File: README.md

# Table of Contents
- [Docker Compose](#docker-compose)
- [Where to get Docker Compose](#where-to-get-docker-compose)
    + [Windows and macOS](#windows-and-macos)
    + [Linux](#linux)
- [Quick Start](#quick-start)
- [Contributing](#contributing)
- [Legacy](#legacy)

# Docker Compose

[](https://github.com/docker/compose/releases/latest)
[](https://pkg.go.dev/github.com/docker/compose/v5)
[](https://github.com/docker/compose/actions?query=workflow%3Aci)
[](https://codecov.io/gh/docker/compose)
[](https://api.securityscorecards.dev/projects/github.com/docker/compose)


Docker Compose is a tool for running multi-container applications on Docker
defined using the [Compose file format](https://compose-spec.io).
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](https://www.mirantis.com/software/swarm/) 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

Docker Compose is included in
[Docker Desktop](https://www.docker.com/products/docker-desktop/)
for Windows and macOS.

### Linux

You can download Docker Compose binaries from the
[release page](https://github.com/docker/compose/releases) 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
-----------

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:

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

Contributing
------------

Want to help develop Docker Compose? Check out our
[contributing documentation](CONTRIBUTING.md).

If you find an issue, please report it on the
[issue tracker](https://github.com/docker/compose/issues/new/choose).

Legacy
-------------

The Python version of Compose is available under the `v1` [branch](https://github.com/docker/compose/tree/v1).

---

## File: docs/reference/compose.md

# docker compose

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


Define and run multi-container applications with Docker

### Subcommands

| Name                            | Description                                                                             |
|:--------------------------------|:----------------------------------------------------------------------------------------|
| [`attach`](compose_attach.md)   | Attach local standard input, output, and error streams to a service's running container |
| [`bridge`](compose_bridge.md)   | Convert compose files into another model                                                |
| [`build`](compose_build.md)     | Build or rebuild services                                                               |
| [`commit`](compose_commit.md)   | Create a new image from a service container's changes                                   |
| [`config`](compose_config.md)   | Parse, resolve and render compose file in canonical format                              |
| [`cp`](compose_cp.md)           | Copy files/folders between a service container and the local filesystem                 |
| [`create`](compose_create.md)   | Creates containers for a service                                                        |
| [`down`](compose_down.md)       | Stop and remove containers, networks                                                    |
| [`events`](compose_events.md)   | Receive real time events from containers                                                |
| [`exec`](compose_exec.md)       | Execute a command in a running container                                                |
| [`export`](compose_export.md)   | Export a service container's filesystem as a tar archive                                |
| [`images`](compose_images.md)   | List images used by the created containers                                              |
| [`kill`](compose_kill.md)       | Force stop service containers                                                           |
| [`logs`](compose_logs.md)       | View output from containers                                                             |
| [`ls`](compose_ls.md)           | List running compose projects                                                           |
| [`pause`](compose_pause.md)     | Pause services                                                                          |
| [`port`](compose_port.md)       | Print the public port for a port binding                                                |
| [`ps`](compose_ps.md)           | List containers                                                                         |
| [`publish`](compose_publish.md) | Publish compose application                                                             |
| [`pull`](compose_pull.md)       | Pull service images                                                                     |
| [`push`](compose_push.md)       | Push service images                                                                     |
| [`restart`](compose_restart.md) | Restart service containers                                                              |
| [`rm`](compose_rm.md)           | Removes stopped service containers                                                      |
| [`run`](compose_run.md)         | Run a one-off command on a service                                                      |
| [`scale`](compose_scale.md)     | Scale services                                                                          |
| [`start`](compose_start.md)     | Start services                                                                          |
| [`stats`](compose_stats.md)     | Display a live stream of container(s) resource usage statistics                         |
| [`stop`](compose_stop.md)       | Stop services                                                                           |
| [`top`](compose_top.md)         | Display the running processes                                                           |
| [`unpause`](compose_unpause.md) | Unpause services                                                                        |
| [`up`](compose_up.md)           | Create and start containers                                                             |
| [`version`](compose_version.md) | Show the Docker Compose version information                                             |
| [`volumes`](compose_volumes.md) | List volumes                                                                            |
| [`wait`](compose_wait.md)       | Block until containers of all (or specified) services stop.                             |
| [`watch`](compose_watch.md)     | Watch build context for service and rebuild/refresh containers when files are updated   |


### Options

| Name                   | Type          | Default | Description                                                                                         |
|:-----------------------|:--------------|:--------|:----------------------------------------------------------------------------------------------------|
| `--all-resources`      | `bool`        |         | Include all resources, even those not used by services                                              |
| `--ansi`               | `string`      | `auto`  | Control when to print ANSI control characters ("never"\|"always"\|"auto")                           |
| `--compatibility`      | `bool`        |         | Run compose in backward compatibility mode                                                          |
| `--dry-run`            | `bool`        |         | Execute command in dry run mode                                                                     |
| `--env-file`           | `stringArray` |         | Specify an alternate environment file                                                               |
| `-f`, `--file`         | `stringArray` |         | Compose configuration files                                                                         |
| `--parallel`           | `int`         | `-1`    | Control max parallelism, -1 for unlimited                                                           |
| `--profile`            | `stringArray` |         | Specify a profile to enable                                                                         |
| `--progress`           | `string`      |         | Set type of progress output (auto, tty, plain, json, quiet)                                         |
| `--project-directory`  | `string`      |         | Specify an alternate working directory(default: the path of the, first specified, Compose file) |
| `-p`, `--project-name` | `string`      |         | Project name                                                                                        |




## Examples

### Use `-f` to specify the name and path of one or more Compose files
Use the `-f` flag to specify the location of a Compose [configuration file](/reference/compose-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:

```console
$ docker compose -f compose.yaml -f compose.admin.yaml run backup_db
```

The `compose.yaml` file might specify a `webapp` service.

```yaml
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.

```yaml
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:

```console
$ 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:

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

You can also combine OCI artifacts with local files:

```console
$ 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:
```console
$ docker compose -f https://github.com/user/repo.git up
```

Using SSH:
```console
$ docker compose -f git@github.com:user/repo.git up
```

You can specify a specific branch, tag, or commit:
```console
$ docker compose -f https://github.com/user/repo.git@main up
$ docker compose -f https://github.com/user/repo.git@v1.0.0 up
$ docker compose -f https://github.com/user/repo.git@abc123 up
```

You can also specify a subdirectory within the repository:
```console
$ 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:

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

### Use `-p` to specify a project name

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.

```console
$ 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

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

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

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

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

# docker compose alpha


Experimental commands

### Subcommands

| Name                              | Description                                                                                          |
|:----------------------------------|:-----------------------------------------------------------------------------------------------------|
| [`viz`](compose_alpha_viz.md)     | EXPERIMENTAL - Generate a graphviz graph from your compose file                                      |
| [`watch`](compose_alpha_watch.md) | EXPERIMENTAL - Watch build context for service and rebuild/refresh containers when files are updated |


### Options

| Name        | Type | Default | Description                     |
|:------------|:-----|:--------|:--------------------------------|
| `--dry-run` |      |         | Execute command in dry run mode |

---

## File: docs/reference/compose_alpha_dry-run.md

# docker compose alpha dry-run


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

---

## File: docs/reference/compose_alpha_generate.md

# docker compose alpha generate


EXPERIMENTAL - Generate a Compose file from existing containers

### Options

| Name            | Type     | Default | Description                               |
|:----------------|:---------|:--------|:------------------------------------------|
| `--dry-run`     | `bool`   |         | Execute command in dry run mode           |
| `--format`      | `string` | `yaml`  | Format the output. Values: [yaml \| json] |
| `--name`        | `string` |         | Project name to set in the Compose file   |
| `--project-dir` | `string` |         | Directory to use for the project          |

---

## File: docs/reference/compose_alpha_publish.md

# docker compose alpha publish


Publish compose application

### Options

| Name                      | Type     | Default | Description                                                                    |
|:--------------------------|:---------|:--------|:-------------------------------------------------------------------------------|
| `--dry-run`               | `bool`   |         | Execute command in dry run mode                                                |
| `--oci-version`           | `string` |         | OCI image/artifact specification version (automatically determined by default) |
| `--resolve-image-digests` | `bool`   |         | Pin image tags to digests                                                      |
| `--with-env`              | `bool`   |         | Include environment variables in the published OCI artifact                    |
| `-y`, `--yes`             | `bool`   |         | Assume "yes" as answer to all prompts                                          |

---

## File: docs/reference/compose_alpha_scale.md

# docker compose alpha scale


Scale services

### Options

| Name        | Type | Default | Description                     |
|:------------|:-----|:--------|:--------------------------------|
| `--dry-run` |      |         | Execute command in dry run mode |
| `--no-deps` |      |         | Don't start linked services     |

---

## File: docs/reference/compose_alpha_viz.md

# docker compose alpha viz


EXPERIMENTAL - Generate a graphviz graph from your compose file

### Options

| Name                 | Type   | Default | Description                                                                                        |
|:---------------------|:-------|:--------|:---------------------------------------------------------------------------------------------------|
| `--dry-run`          | `bool` |         | Execute command in dry run mode                                                                    |
| `--image`            | `bool` |         | Include service's image name in output graph                                                       |
| `--indentation-size` | `int`  | `1`     | Number of tabs or spaces to use for indentation                                                    |
| `--networks`         | `bool` |         | Include service's attached networks in output graph                                                |
| `--ports`            | `bool` |         | Include service's exposed ports in output graph                                                    |
| `--spaces`           | `bool` |         | If given, space character ' ' will be used to indent,otherwise tab character '\t' will be used |

---

## File: docs/reference/compose_alpha_watch.md

# docker compose alpha watch


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

### Options

| Name        | Type | Default | Description                                   |
|:------------|:-----|:--------|:----------------------------------------------|
| `--dry-run` |      |         | Execute command in dry run mode               |
| `--no-up`   |      |         | Do not build & start services before watching |
| `--quiet`   |      |         | hide build output                             |

---

## File: docs/reference/compose_attach.md

# docker compose attach


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

### Options

| Name            | Type     | Default | Description                                               |
|:----------------|:---------|:--------|:----------------------------------------------------------|
| `--detach-keys` | `string` |         | Override the key sequence for detaching from a container. |
| `--dry-run`     | `bool`   |         | Execute command in dry run mode                           |
| `--index`       | `int`    | `0`     | index of the container if service has multiple replicas.  |
| `--no-stdin`    | `bool`   |         | Do not attach STDIN                                       |
| `--sig-proxy`   | `bool`   | `true`  | Proxy all received signals to the process                 |

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

# Docs @ Docker





Welcome to the Docker Documentation repository. This is the source for the [Docker Docs Website](https://docs.docker.com/).

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

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

- Click **[New issue](https://github.com/docker/docs/issues/new)** on the docs repository, or
- Click **Request changes** in the right column of every page on
  [docs.docker.com](https://docs.docker.com/), or
- Click **Give feedback** on every page in the docs.

To get community support, use the [Docker Community Slack](https://dockr.ly/comm-slack). Personalized support is available
through the Docker Pro, Team, and Business subscriptions. See [Docker
Pricing](https://www.docker.com/pricing?ref=Docs&refAction=DocsReadme) 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

We welcome contributions! To get started:

- [CONTRIBUTING.md](CONTRIBUTING.md) - Contribution workflow and setup
- [STYLE.md](STYLE.md) - Writing style and content guidelines
- [COMPONENTS.md](COMPONENTS.md) - Component and shortcode usage

## Copyright and license

Copyright 2013-2026 Docker, Inc., released under the [Apache 2.0 license](https://github.com/docker/docs/blob/main/LICENSE).