Compose file versions and upgrading

Estimated reading time: 2 minutes

The Compose file is a YAML file defining services, networks, and volumes for a Docker application.

Versioning

Earlier releases of Docker Compose used a version field in the Compose file to define supported attributes. The latest and recommended version of the Compose file format is defined by the Compose Specification. This format merges the legacy 2.x and 3.x file formats and is implemented by Compose 1.27.0+ and Compose V2.

.important}

For modern usage, you should not declare a version attribute in your Compose file. File format is described by the Compose Specification.

Legacy

There are three legacy versions of the Compose file format:

• Version 1. (Obsolete)

• 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, 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.

These differences are explained below.

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.

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 on extends, see Extending services.)

• Added: deploy

Upgrading

The Compose Specification defines all the attributes from both versions 2.x and 3.x, so basically you don’t need anything changed for your Compose file to be compliant with the Specification. Just the version attribute will be ignored, you can remove it.