We’re thrilled to announce the General Availability of Docker Compose Version 2 (aka V2)!

We launched the first version of Compose V2 in June of 2021. Thanks to your feedback, we’ve made numerous improvements since our initial rollout — and have seen a steady increase in adoption over the last 10 months. We’re hearing a lot of good things about V2!  Currently, 78% of Docker Compose users running the latest version of Docker Desktop use Compose V2, so we’re confident in making it generally available for production workflows.

What you Need to Know About the Transition

When is Compose V2 GA and what does it mean?

April 26, 2022 marks the GA of Docker Compose V2. Starting today, Compose V2 is the standard across all documentation, and Compose V2 will become the developer default on Docker Desktop. However, you can continue aliasing docker-compose to docker compose and opt-out of V2 via the Docker Desktop UI — or by entering the docker-compose disable-v2 command.

What’ll happen to Compose V1?

We’ve now marked Compose V1 as deprecated. Only high-priority security patches and critical bug fixes will apply to V1 until the next milestone. Later in this blog, we’ll outline a proposed timeline for Docker Compose V1’s end of life (EOL) — which includes six months of critical security-and-bug fixes, and a one year grace period for opting out of V2.

Currently, we have no plans to remove aliasing of docker-compose to docker compose. If you have any questions or concerns, we welcome your feedback on our open roadmap issue. We’ll gather your feedback while continually tracking V2’s usage, and make adjustments as we go along.

What do I need to do as a developer?

In most cases, you won’t need to do anything. Docker Desktop versions 3.4+ have Compose V2 installed automatically. On Docker Desktop version 4.4.2+, we enable aliasing of docker-compose syntax to docker compose by default. This lets you use V2 as a drop-in replacement for V1 while requiring minimal (if any) updates to your scripts.

You can see if you’re using aliasing via the “General” settings tab in Docker Desktop, by checking whether “Use Docker Compose V2” is selected. Please reference the “What do I need to do if I’m still using Compose V1” section of this blog for more information on migration. If you encounter any incompatibilities, please submit them here.

What if I use Linux?

Docker Desktop for Linux is now in beta and includes Compose V2. Alternatively, you can manually install Docker Compose V2 for Linux. In Moby v20.10.13, we’ve included compose-plugin as an optional Docker CLI plugin for easier installation. Check out our documentation for more information.

Why is Docker making this transition and why should I use V2?

Compose V2 offers all of Compose V1’s functionality to help you efficiently run your multi-container applications. The transition to Go was one of our most liked roadmap items and has enabled us to deliver more features at a faster rate. These are now integrated into the Docker CLI, creating a seamless user experience across Docker’s tools. Read more about key features introduced in V2.

Oh, and what’s the Compose Octopus’ name?

We don’t have one yet! Help us name our friend by heading over to GitHub — both to submit your own names and vote on your favorites!

Next, let’s tackle the process of transitioning to V2 and the benefits of doing so.

What should I do if I’m still using Compose V1?

Ensure you have Compose V2 installed

Docker Desktop automatically includes Docker Compose V2. Additionally, Docker Desktop for Linux (Beta) comes with Compose V2. You may also manually install Docker Compose V2 on Linux, if you prefer. We’ve also included the optional compose-plugin within Moby v20.10.13 — in the Docker CLI — to simplify installation. Note that Compose V2 is a Go project, so it won’t be available as a Python library. Only Compose V1 is available via pip. For more information, please refer to our documentation.

Alias docker-compose to docker compose

Within Docker Desktop, toggle the “Use Docker Compose V2” option under the “General” tab. This will alias docker-compose commands to docker compose. You can easily use V2 as a drop-in replacement for V1 with minimal script updates.

 

Ensure Compatibility Between V1 and V2

Ensuring compatibility between Compose V1 and Compose V2 is critical in helping you leverage Compose V2, without disrupting your daily workflows. Below are two key changes introduced in Compose V2, plus their mitigation steps. Additionally, we’ve deprecated a few Compose V1 flags which aren’t implemented in Compose V2. To learn more about these changes, please read our compatibility documentation.

 

What’s Changed	Potential Impact	Mitigation
BuildKit support is native within V2 and enabled by default, as it is in the Docker CLI.	Developers on V2 will use BuildKit by default.	Opt out using by setting DOCKER_BUILDKIT=0
Container names now use hyphens as separators instead of underscores.	If you rely on container names in scripts, this will cause breaking changes. Generally, we caution against relying on container names.	You can turn this off by passing the flag “–compatibility”

 

Docker Compose V2 is a drop-in replacement for Compose V1. In most cases, you can remove the dash or enable aliasing of docker-compose to docker compose and continue without additional changes. If you experience any issues while transitioning, please submit feedback to our Compose issue repository and we’ll prioritize it accordingly.

What about Docker Compose V1?

We want you to have ample time to transition to Compose V2. We won’t sunset Docker Compose V1 immediately, and developers can still revert to V1 temporarily.

Here’s what Docker Compose V2’s graduation means for you:

• The Docker Compose V2 branch is now the default on GitHub.
• You can still find Docker Compose V1 in the `master` branch.
• Compose V1 is marked as deprecated, and we’ll begin patching only high-severity vulnerabilities or fixing critical bugs until the next milestone.
• Developers can continue to alias docker-compose to use docker compose.
• Developers can continue opting out of V2 — via the Docker Desktop UI, or through the docker-compose disable-v2 command.
• Compose V1 remains open source, though new feature development is ending. We’ll continue monitoring any community-submitted bug fixes or security patches and merging them as needed.

Proposed Compose V1 End-of-Life Timeline

Given the numerous successful transitions to Compose V2 so far, we’ve created the following timeline for Docker Compose V1’s end of life (EOL):

We encourage you to share your feedback via our GitHub roadmap issue. We’ll monitor this feedback alongside V2’s usage and make adjustments accordingly.

What are the benefits of Compose V2?

1) Fast Delivery of New Features Within the Docker CLI

The transition to Compose V2 comes with many useful new features:

• Support for GPU machines – Compose services can define GPU device reservations if the Docker host contains such devices, and when the Docker Daemon is set accordingly.
• Profiles support – Profiles let you adapt your Compose application model for various usages and environments, through selective service enablement.
• The docker compose ls command now lets you view a full list of your Compose apps.
• The docker compose cp command lets you copy files and folders between your service container and your local filesystem.

We ship these features via the Docker CLI. Each Docker Desktop automatically applies any updates to the CLI, which reduces your management workload.

2) Seamless Path to Production

What if you could easily compose up a project and run it directly within your AWS or ECS environment — or within Azure ACI? You can do this with Compose V2 thanks to new Cloud Integrations.

If you use Docker Compose for local development and ACI or ECS for production, deploying Docker Compose applications to the cloud is now much easier. You can compose “up” an application on cloud platforms by simply switching the Docker context, and launching your app on Amazon ECS or Microsoft ACI.

The Compose specification within V2 enables this. The Compose specification lets you define multi-container applications that are platform agnostic. Other programs can use the specification to validate and run these files. This also introduces compose-go, which is Go’s implementation of Compose-file parsing and representation. This is common across implementations using Amazon ECS, Microsoft ACI, or Kubernetes integrations.

3) Creating a Homogenous Docker Ecosystem in Go

Prior to Compose V2, we wrote Docker Compose V1 in Python — an outlier within the Docker ecosystem. Conversely, Compose V2 is written in Go. V2 can therefore vendor code from Moby, the CLI, or any Go-based projects. With Docker Compose’s transition to Go, we don’t need to rewrite any new features or bug fixes in Python.

We can now integrate a fix from the Docker CLI more easily with Compose. This gives us a canonical location for hosting shared functions across the Docker ecosystem, and promotes seamless reuse. Accordingly, we can quickly deliver more value across our tooling. We can also easily add updates to Compose from other Docker tools, like BuildKit.

For example, we now use the same code for the run and exec commands in both Compose and the Docker CLI — letting us preserve well-tested behaviors while running both docker and docker compose. Everything down to the log output remains consistent, making it easier for developers to switch between them.

4) Easier Update-and-Dependency Management with Compose Binaries

With Go, we can now release a static binary (avoiding some problems like glibc vs libmusl on GNU/Linux), which was previously impossible. This is because Python doesn’t have a built-in compiler. This forced us to rely upon pyinstaller to generate a binary for leading platforms (GNU/Linux, macOS, and Windows). For more heterogeneous platforms, V1 relies on the PyPI (by pip install), which complicates dependency management. You could have a wide range of dependency combinations already installed.

The Go language unlocks cross compilation through $GOOS, $GOARCH, and possibly $GOARM (refer to Go’s documentation for an exhaustive list). You can then use static binaries in a Raspberry Pi and avoid pip install.

Finally, running things natively is much faster!

5. Run Commands Without a Compose File

Last but not least, container labels let you recreate information contained in your YAML files. This feature lets you manage a running project just by adding –project-name to the command line so you can run things like docker compose start/stop/pause/down/ps/exec… without the original Compose file and environment variable. Simply grab an existing project name that you’d previously set by entering –project-name (-p).

For example, the following command wouldn’t require you to be in a folder with the project name, nor require you to place your Compose file in the current directory:

$ docker compose --project-name myproject down

Thanks for supporting Docker Compose’s evolution, as it joins the Docker CLI’s family of plugins! We’re excited to keep enhancing the Compose V2 user experience. Test out V2 the next time you use Docker Compose by replacing the hyphen with a space. It’s as simple as that!