docsCreated with Sketch.

History of Docker Compose

Important

From July 2023 Compose V1 stopped receiving updates. It's also no longer available in new releases of Docker Desktop.

Compose V2 is included with all currently supported versions of Docker Desktop. For more information, see Migrate to Compose V2.

Docker's documentation refers to and describes Compose V2 functionality.

This page provides a brief history of the major versions and file format revisions of Docker Compose.

The currently supported version of Compose is V2, which uses YAML files as defined by the Compose specificationopen_in_new.

For users supporting projects originally targeting older versions of Compose, this can serve as a guide to understanding compatibility and the evolution of changes.

Docker Compose CLI versioning

There are two major versions of Docker Compose, otherwise known as the command-line binary.

Compose V1 was first released in 2014. It was written in Python, and is invoked as docker-compose. Typically, Compose V1 projects include a version field in YAML with values ranging from 2.0 to 3.8.

Compose V2 was announced in 2020, is written in Go, and is invoked as docker compose. Compose V2 ignores the version field in YAML.

Compose file format versioning

With Compose V1, projects declared a Compose file format version in YAML.

Three major versions of the Compose file format for Compose V1 were released:

Compose file format 1 was substantially different than all following formats, lacking a top-level services key. Its usage is historical and files written in this format don't run with Compose V2.

Compose file format 2.x and 3.x were very similar to each other, but the latter introduced many new options targeted at Swarm deployments.

To address confusion around Compose CLI versioning, Compose file format versioning, and feature parity depending on whether Swarm mode was in use, file format 2.x and 3.x were merged into the Compose Specificationopen_in_new. Unlike the prior file formats, the Compose Specification is rolling and eliminates the version field in YAML.

Compose V2 uses the Compose Specification for project definition. The version field should be omitted and is ignored if present.

To make migration easier, Compose V2 has backwards compatibility for certain elements that have been deprecated or changed between Compose file format 2.x/3.x and the Compose Specification. In these cases, a warning is logged when running Compose V2 commands, and you should update your YAML accordingly. Future versions of Compose may return an error in these cases.