Compose file versions and upgradingEstimated reading time: 14 minutes
The 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.
There are several versions of the Compose file format 1, 2, 2.x,
This table shows which Compose file versions support specific
|Compose file format||Docker Engine release|
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
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
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' or version:
'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' or version: '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.
Compose files that do not declare a version are considered version
1”. In those files, all the services are declared at the root of
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
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.
webbuild: . ports- "5000:5000" volumes- .:/code links- redis
Compose files using the version 2 s