Compose file versions and upgrading
Estimated reading time: 14 minutesThe Compose file is a YAML file defining services, networks, and volumes for a Docker application.
The Compose file formats are now described in these references, specific to each version.
Reference file | What changed in this version |
---|---|
Version 3 (most current, and recommended) | Version 3 updates |
Version 2 | Version 2 updates |
Version 1 | Version 1 updates |
The topics below explain the differences among the versions, Docker Engine compatibility, and how to upgrade.
Compatibility matrix
There are several versions of the Compose file format – 1, 2, 2.x, and 3.x
This table shows which Compose file versions support specific Docker releases.
Compose file format | Docker Engine release |
---|---|
3.7 | 18.06.0+ |
3.6 | 18.02.0+ |
3.5 | 17.12.0+ |
3.4 | 17.09.0+ |
3.3 | 17.06.0+ |
3.2 | 17.04.0+ |
3.1 | 1.13.1+ |
3.0 | 1.13.0+ |
2.4 | 17.12.0+ |
2.3 | 17.06.0+ |
2.2 | 1.13.0+ |
2.1 | 1.12.0+ |
2.0 | 1.10.0+ |
1.0 | 1.9.1.+ |
In addition to Compose file format versions shown in the table, the Compose itself is on a release schedule, as shown in Compose releases, but file format versions do not necessarily increment with each release. For example, Compose file format 3.0 was first introduced in Compose release 1.10.0, and versioned gradually in subsequent releases.
Looking for more detail on Docker and Compose compatibility?
We recommend keeping up-to-date with newer releases as much as possible. However, if you are using an older version of Docker and want to determine which Compose release is compatible, refer to the Compose release notes. Each set of release notes gives details on which versions of Docker Engine are supported, along with compatible Compose file format versions. (See also, the discussion in issue #3404.)
For details on versions and how to upgrade, see Versioning and Upgrading.
Versioning
There are currently three versions of the Compose file format:
-
Version 1, the legacy format. This is specified by omitting a
version
key at the root of the YAML. -
Version 2.x. This is specified with a
version: '2'
orversion: '2.1'
, etc., entry at the root of the YAML. -
Version 3.x, the latest and recommended version, designed to be cross-compatible between Compose and the Docker Engine’s swarm mode. This is specified with a
version: '3'
orversion: '3.1'
, etc., entry at the root of the YAML.
v2 and v3 Declaration
Note: When specifying the Compose file version to use, make sure to specify both the major and minor numbers. If no minor version is given,
0
is used by default and not the latest minor version.
The Compatibility Matrix shows Compose file versions mapped to Docker Engine releases.
To move your project to a later version, see the Upgrading section.
Note: If you’re using multiple Compose files or extending services, each file must be of the same version - you cannot, for example, mix version 1 and 2 in a single project.
Several things differ depending on which version you use:
- The structure and permitted configuration keys
- The minimum Docker Engine version you must be running
- Compose’s behaviour with regards to networking
These differences are explained below.
Version 1
Compose files that do not declare a version are considered “version 1”. In those files, all the services are declared at the root of the document.
Version 1 is supported by Compose up to 1.6.x. It will be deprecated in a future Compose release.
Version 1 files cannot declare named volumes, networks or build arguments.
Compose does not take advantage of networking when you
use version 1: every container is placed on the default bridge
network and is
reachable from every other container at its IP address. You need to use
links to enable discovery between containers.
Example:
web:
build: .
ports:
- "5000:5000"
volumes:
- .:/code
links:
- redis
redis:
image: redis
Version 2
Compose files using the version 2 syntax must indicate the version number at
the root of the document. All services
must be declared under the services
key.
Version 2 files are supported by Compose 1.6.0+ and require a Docker Engine of version 1.10.0+.
Named volumes can be declared under the
volumes
key, and networks can be declared
under the networks
key.
By default, every container joins an application-wide default network, and is discoverable at a hostname that’s the same as the service name. This means links are largely unnecessary. For more details, see Networking in Compose.
Note: When specifying the Compose file version to use, make sure to specify both the major and minor numbers. If no minor version is given,
0
is used by default and not the latest minor version. As a result, features added in later versions will not be supported. For example:version: "2"
is equivalent to:
version: "2.0"
Simple example:
version: "2.4"
services:
web:
build: .
ports:
- "5000:5000"
volumes:
- .:/code
redis:
image: redis
A more extended example, defining volumes and networks:
version: "2.4"
services:
web:
build: .
ports:
- "5000:5000"
volumes:
- .:/code
networks:
- front-tier
- back-tier
redis:
image: redis
volumes:
- redis-data:/var/lib/redis
networks:
- back-tier
volumes:
redis-data:
driver: local
networks:
front-tier:
driver: bridge
back-tier:
driver: bridge
Several other options were added to support networking, such as:
-
The
depends_on
option can be used in place of links to indicate dependencies between services and startup order.version: "2.4" services: web: build: . depends_on: - db - redis redis: image: redis db: image: postgres
Variable substitution also was added in Version 2.
Version 2.1
An upgrade of version 2 that introduces new parameters only available with Docker Engine version 1.12.0+. Version 2.1 files are supported by Compose 1.9.0+.
Introduces the following additional parameters:
link_local_ips
isolation
in build configurations and service definitionslabels
for volumes and networksname
for volumesuserns_mode
healthcheck
sysctls
pids_limit
oom_kill_disable
cpu_period
Version 2.2
An upgrade of version 2.1 that introduces new parameters only available with Docker Engine version 1.13.0+. Version 2.2 files are supported by Compose 1.13.0+. This version also allows you to specify default scale numbers inside the service’s configuration.
Introduces the following additional parameters:
Version 2.3
An upgrade of version 2.2 that introduces new parameters only available with Docker Engine version 17.06.0+. Version 2.3 files are supported by Compose 1.16.0+.
Introduces the following additional parameters:
target
,extra_hosts
andshm_size
for build configurationsstart_period
forhealthchecks
- “Long syntax” for volumes
runtime
for service definitionsdevice_cgroup_rules
Version 2.4
An upgrade of version 2.3 that introduces new parameters only available with Docker Engine version 17.12.0+. Version 2.4 files are supported by Compose 1.21.0+.
Introduces the following additional parameters:
platform
for service definitions- Support for extension fields at the root of service, network, and volume definitions
Version 3
Designed to be cross-compatible between Compose and the Docker Engine’s swarm mode, version 3 removes several options and adds several more.
-
Removed:
volume_driver
,volumes_from
,cpu_shares
,cpu_quota
,cpuset
,mem_limit
,memswap_limit
,extends
,group_add
. See the upgrading guide for how to migrate away from these. (For more information onextends
, see Extending services.) -
Added: deploy
Note: When specifying the Compose file version to use, make sure to specify both the major and minor numbers. If no minor version is given,
0
is used by default and not the latest minor version. As a result, features added in later versions will not be supported. For example:version: "3"
is equivalent to:
version: "3.0"
Version 3.3
An upgrade of version 3 that introduces new parameters only available with Docker Engine version 17.06.0+, and higher.
Introduces the following additional parameters:
Version 3.4
An upgrade of version 3 that introduces new parameters. It is only available with Docker Engine version 17.09.0 and higher.
Introduces the following additional parameters:
target
andnetwork
in build configurationsstart_period
forhealthchecks
order
for update configurationsname
for volumes
Version 3.5
An upgrade of version 3 that introduces new parameters. It is only available with Docker Engine version 17.12.0 and higher.
Introduces the following additional parameters:
isolation
in service definitionsname
for networks, secrets and configsshm_size
in build configurations
Version 3.6
An upgrade of version 3 that introduces new parameters. It is only available with Docker Engine version 18.02.0 and higher.
Introduces the following additional parameters:
tmpfs
size fortmpfs
-type mounts
Version 3.7
An upgrade of version 3 that introduces new parameters. It is only available with Docker Engine version 18.06.0 and higher.
Introduces the following additional parameters:
init
in service definitionsrollback_config
in deploy configurations- Support for extension fields at the root of service, network, volume, secret and config definitions
Upgrading
Version 2.x to 3.x
Between versions 2.x and 3.x, the structure of the Compose file is the same, but several options have been removed:
-
volume_driver
: Instead of setting the volume driver on the service, define a volume using the top-levelvolumes
option and specify the driver there.version: "3.7" services: db: image: postgres volumes: - data:/var/lib/postgresql/data volumes: data: driver: mydriver
-
volumes_from
: To share a volume between services, define it using the top-levelvolumes
option and reference it from each service that shares it using the service-levelvolumes
option. -
cpu_shares
,cpu_quota
,cpuset
,mem_limit
,memswap_limit
: These have been replaced by the resources key underdeploy
.deploy
configuration only takes effect when usingdocker stack deploy
, and is ignored bydocker-compose
. extends
: This option has been removed forversion: "3.x"
Compose files. (For more information, see Extending services.)group_add
: This option has been removed forversion: "3.x"
Compose files.pids_limit
: This option has not been introduced inversion: "3.x"
Compose files.link_local_ips
innetworks
: This option has not been introduced inversion: "3.x"
Compose files.
Version 1 to 2.x
In the majority of cases, moving from version 1 to 2 is a very simple process:
- Indent the whole file by one level and put a
services:
key at the top. - Add a
version: '2'
line at the top of the file.
It’s more complicated if you’re using particular configuration features:
-
dockerfile
: This now lives under thebuild
key:build: context: . dockerfile: Dockerfile-alternate
-
log_driver
,log_opt
: These now live under thelogging
key:logging: driver: syslog options: syslog-address: "tcp://192.168.0.42:123"
-
links
with environment variables: As documented in the environment variables reference, environment variables created by links have been deprecated for some time. In the new Docker network system, they have been removed. You should either connect directly to the appropriate hostname or set the relevant environment variable yourself, using the link hostname:web: links: - db environment: - DB_PORT=tcp://db:5432
-
external_links
: Compose uses Docker networks when running version 2 projects, so links behave slightly differently. In particular, two containers must be connected to at least one network in common in order to communicate, even if explicitly linked together.Either connect the external container to your app’s default network, or connect both the external container and your service’s containers to an external network.
-
net
: This is now replaced by network_mode:net: host -> network_mode: host net: bridge -> network_mode: bridge net: none -> network_mode: none
If you’re using
net: "container:[service name]"
, you must now usenetwork_mode: "service:[service name]"
instead.net: "container:web" -> network_mode: "service:web"
If you’re using
net: "container:[container name/id]"
, the value does not need to change.net: "container:cont-name" -> network_mode: "container:cont-name" net: "container:abc12345" -> network_mode: "container:abc12345"
-
volumes
with named volumes: these must now be explicitly declared in a top-levelvolumes
section of your Compose file. If a service mounts a named volume calleddata
, you must declare adata
volume in your top-levelvolumes
section. The whole file might look like this:version: "2.4" services: db: image: postgres volumes: - data:/var/lib/postgresql/data volumes: data: {}
By default, Compose creates a volume whose name is prefixed with your project name. If you want it to just be called
data
, declare it as external:volumes: data: external: true
Compatibility mode
docker-compose
1.20.0 introduces a new --compatibility
flag designed to
help developers transition to version 3 more easily. When enabled,
docker-compose
reads the deploy
section of each service’s definition and
attempts to translate it into the equivalent version 2 parameter. Currently,
the following deploy keys are translated:
- resources limits and memory reservations
- replicas
- restart_policy
condition
andmax_attempts
All other keys are ignored and produce a warning if present. You can review
the configuration that will be used to deploy by using the --compatibility
flag with the config
command.
Do not use this in production!
We recommend against using
--compatibility
mode in production. Because the resulting configuration is only an approximate using non-Swarm mode properties, it may produce unexpected results.