---
created: '2026-04-15T18:11:45+00:00'
id: 9ee96ac8-e1ff-4946-b08f-680be1d1b2bb
keywords:
- docker compose
- compose.yaml
- compose.yml
- docker-compose
- multi-container
- services
- networks
- volumes
- build
- environment variables
- depends_on
- docker documentation
- compose specification
- configs
- secrets
- deploy
- healthcheck
- docker compose up
- docker compose down
- docker compose build
- docker compose watch
links: []
modified: '2026-04-15T18:11:45+00:00'
summary: Comprehensive reference for Docker Compose covering the Compose file specification
  (compose.yaml), all top-level elements (services, networks, volumes, configs, secrets),
  key CLI commands, build specification, environment variable interpolation, and usage
  examples. Derived from official Docker documentation (docs.docker.com).
tags:
- reference
- docker
- compose
- containers
- devops
- orchestration
title: Docker Compose Reference
---

# Docker Compose Reference

## Overview

Docker Compose is a tool for defining and running multi-container applications. You use a YAML configuration file (`compose.yaml`) to configure your application's services, networks, and volumes. Then with a single command (`docker compose up`), you create and start all services from your configuration.

Compose works in all environments: production, staging, development, testing, and CI workflows. It manages the whole lifecycle: start, stop, rebuild, view status, stream logs, run one-off commands.

> **Source:** Official Docker Compose documentation — https://docs.docker.com/compose/ | https://docs.docker.com/reference/compose-file/ | Fetched: July 2025

---

## Compose File (`compose.yaml`)

| Aspect | Detail |
|---|---|
| **Default path** | `compose.yaml` (preferred) or `compose.yml` |
| **Legacy paths** | `docker-compose.yaml` and `docker-compose.yml` (backwards compatibility) |
| **Conflict resolution** | If both canonical and legacy exist, Compose prefers `compose.yaml` |
| **Merging** | Multiple Compose files can be merged; simple attributes are overridden by the highest-order file, lists are merged by appending |
| `include` | Reference other Compose files from different teams |
| `extends` | Share common configurations among services (supports `file` and `service` keys) |

---

## Top-Level Elements

The Compose Specification defines the following top-level elements:

### `services` (required)

A map whose keys are service names and values are service definitions. Key service attributes include:

#### Core

| Attribute | Description |
|---|---|
| `image` | Docker image to use |
| `build` | Build config (context, dockerfile, args, target, cache_from/cache_to, tags, secrets, ssh, network, no_cache, platforms, etc.) |
| `command` | Overrides default CMD from image |
| `entrypoint` | Overrides default ENTRYPOINT from image |
| `container_name` | Custom container name (prevents scaling) |
| `hostname` | Custom hostname (must be valid RFC 1123) |
| `domainname` | Custom domain name |

#### Networking

| Attribute | Description |
|---|---|
| `ports` | Publish ports (`HOST:CONTAINER` format) |
| `expose` | Expose ports to linked services only (not published to host) |
| `networks` | Networks to join |
| `network_mode` | Special network mode (`host`, `none`, `service:name`) |
| `dns` | Custom DNS servers |
| `dns_opt` | DNS options |
| `dns_search` | DNS search domains |
| `extra_hosts` | Additional hostname mappings |

#### Storage

| Attribute | Description |
|---|---|
| `volumes` | Volume mounts (supports short and long syntax with `type`, `source`, `target`, `read_only`, etc.) |
| `volumes_from` | Mount volumes from another service/container |
| `tmpfs` | Temporary filesystem mounts |

#### Dependencies & Ordering

| Attribute | Description |
|---|---|
| `depends_on` | Control startup/shutdown order. **Short syntax**: service names. **Long syntax**: `condition` (`service_started`, `service_healthy`, `service_completed_successfully`), `required` (bool), `restart` (bool) |

#### Configuration & Secrets

| Attribute | Description |
|---|---|
| `environment` | Container environment variables (map or array syntax) |
| `env_file` | Files containing environment variables (supports `required` and `format` attributes) |
| `configs` | Grant access to configs (short or long syntax with `source`, `target`, `uid`, `gid`, `mode`) |
| `secrets` | Grant access to secrets (short or long syntax) |

#### Resource Limits

| Attribute | Description |
|---|---|
| `cpu_count`, `cpu_percent`, `cpu_shares` | CPU allocation controls |
| `cpu_period`, `cpu_quota` | CPU throttling |
| `cpu_rt_runtime`, `cpu_rt_period` | Real-time CPU scheduling |
| `cpus`, `cpuset` | CPU count and affinity |
| `mem_limit`, `mem_reservation` | Memory limits |
| `mem_swappiness`, `memswap_limit` | Swap controls |
| `blkio_config` | Block I/O limits (`weight`, `weight_device`, `device_read/write_bps`, `device_read/write_iops`) |
| `pids_limit` | Process ID limit |

#### Health & Lifecycle

| Attribute | Description |
|---|---|
| `healthcheck` | Container health check configuration |
| `restart` | Restart policy (`no`, `always`, `on-failure`, `unless-stopped`) |
| `stop_grace_period` | Grace period before SIGKILL |
| `stop_signal` | Signal to send on stop |
| `init` | Run an init process inside the container |
| `post_start`, `pre_stop` | Lifecycle hooks |

#### Security & Isolation

| Attribute | Description |
|---|---|
| `cap_add`, `cap_drop` | Linux capabilities |
| `security_opt` | Security options |
| `privileged` | Give full access to host |
| `read_only` | Read-only root filesystem |
| `user` | Username/UID |
| `group_add` | Additional groups |
| `userns_mode` | User namespace mode |
| `cgroup`, `cgroup_parent` | Cgroup settings |
| `isolation` | Container isolation technology |
| `devices` | Device mappings |
| `device_cgroup_rules` | Device cgroup rules |

#### Logging

| Attribute | Description |
|---|---|
| `logging` | Logging configuration with `driver` and `options` |

#### Other

| Attribute | Description |
|---|---|
| `labels` | Metadata labels |
| `annotations` | Container annotations |
| `scale` | Scale to N containers |
| `profiles` | Service profiles for selective startup |
| `platform` | Target platform |
| `pull_policy` | Image pull policy |
| `runtime` | Container runtime |
| `shm_size` | Shared memory size |
| `stdin_open`, `tty` | Interactive mode |
| `ulimits` | System ulimit settings |
| `sysctls` | Kernel parameters |
| `working_dir` | Working directory inside container |
| `extends` | Extend another service's configuration |
| `deploy` | Deployment config (`replicas`, `update_config`, `rollback_config`, `resources`, `restart_policy`, `placement`, `labels`, `mode`) |
| `develop` | Development config (Compose Watch) |
| `models` | AI model configuration (Compose Model Runner) |

---

### `networks`

Define named networks for service communication.

| Attribute | Description |
|---|---|
| `driver` | `bridge` (default), `overlay`, `host`, `none`, or custom |
| `driver_opts` | Driver-specific options |
| `attachable` | Allow standalone containers to attach (for overlay networks) |
| `external` | Reference an existing network |
| `internal` | No external connectivity |
| `enable_ipv4`, `enable_ipv6` | IP version support |
| `ipam` | Custom IPAM config (`driver`, `config` with `subnet`/`ip_range`/`gateway`/`aux_addresses`, `options`) |
| `labels` | Metadata |
| `name` | Custom network name |

> **Default network:** When no networks are declared, Compose creates an implicit `default` network. All services without explicit `networks` join it.

---

### `volumes`

Define named volumes for persistent data.

| Attribute | Description |
|---|---|
| `driver` | Volume driver |
| `driver_opts` | Driver-specific options (e.g., NFS config) |
| `external` | Reference an existing volume |
| `labels` | Metadata |
| `name` | Custom volume name |

---

### `configs`

Runtime configuration data mounted as files into containers.

| Attribute | Description |
|---|---|
| `file` | File containing config content |
| `external` | Reference existing config |
| `name` | Custom name |
| `labels` | Metadata |

---

### `secrets`

Sensitive data (passwords, keys, certificates) mounted as files.

| Attribute | Description |
|---|---|
| `file` | File containing secret content |
| `external` | Reference existing secret |
| `name` | Custom name |
| `labels` | Metadata |

---

### `name` (top-level)

Project name used to group and isolate resources.

---

## Key Commands

| Command | Description |
|---|---|
| `docker compose up` | Create and start all services |
| `docker compose up -d` | Run in detached (background) mode |
| `docker compose down` | Stop and remove containers, networks |
| `docker compose down --volumes` | Also remove volumes |
| `docker compose build` | Build or rebuild services |
| `docker compose start` | Start existing services |
| `docker compose stop` | Stop services (without removing) |
| `docker compose restart` | Restart services |
| `docker compose ps` | List running services and their status |
| `docker compose logs` | View service logs |
| `docker compose exec` | Execute command in running container |
| `docker compose run` | Run a one-off command on a service |
| `docker compose config` | Validate and view the Compose file |
| `docker compose pull` | Pull service images |
| `docker compose push` | Push service images |
| `docker compose watch` | Watch for file changes and sync (development) |
| `docker compose scale` | Scale services |

---

## Compose Build Specification

The `build` section defines how to build images from source:

| Attribute | Description |
|---|---|
| `context` | Build context path or Git URL |
| `dockerfile` / `dockerfile_inline` | Alternate Dockerfile |
| `args` | Build arguments (ARG values) |
| `target` | Multi-stage build target |
| `cache_from`, `cache_to` | Build cache sources/targets |
| `secrets` | Build-time secrets |
| `ssh` | SSH authentication for builds |
| `network` | Network for RUN instructions |
| `no_cache` | Disable cache |
| `tags` | Additional image tags |
| `platforms` | Target platforms |
| `additional_contexts` | Named build contexts |
| `labels` | Image labels |
| `ulimits` | Build ulimits |
| `entitlements`, `privileged`, `isolation` | Security settings |
| `provenance`, `sbom` | Attestation settings |
| `shm_size` | Shared memory for build |

---

## Environment Variables & Interpolation

- Variables in `compose.yaml` use `${VARIABLE:-default}` syntax
- `env_file` loads from files; `environment` takes precedence
- `.env` file in project directory provides default values
- Compose-specific variables: `COMPOSE_PROJECT_NAME`, `COMPOSE_FILE`, `COMPOSE_PROFILES`, `COMPOSE_PATH_SEPARATOR`, etc.

---

## Quickstart Example

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

---

## Advanced Example

```yaml
services:
  frontend:
    image: example/webapp
    ports:
      - "443:8043"
    networks:
      - front-tier
      - back-tier
    configs:
      - httpd-config
    secrets:
      - server-certificate

  backend:
    image: example/database
    volumes:
      - db-data:/etc/data
    networks:
      - back-tier

volumes:
  db-data:
    driver: flocker
    driver_opts:
      size: "10GiB"

configs:
  httpd-config:
    external: true

secrets:
  server-certificate:
    external: true

networks:
  front-tier: {}
  back-tier: {}
```