How to Upgrade to Docker Compose v2

After almost a year in beta, Docker Compose v2 is generally available as the container management tool’s stable release. Most users should be able to make the switch today. In this guide, we’ll show you how to prepare and apply your upgrade.

What’s New In v2?

Docker Compose v2 brings Compose’s familiar functionality to the regular docker CLI. Instead of interacting with a separate docker-compose binary, you now use docker compose. Compose is integrated into Docker.

You can replace commands like this:

$ docker-compose up -d

With the following invocation:

$ docker compose up -d

Compose v2 also comes with a few new features that improve the user experience:

• You can use docker compose cp to copy files between your host and containers.
• Cloud providers are valid targets, letting you docker compose up to deploy containers to Amazon ECS or Microsoft ACI.
• Service profiles are fully supported, facilitating selective inclusion of containers in a stack.
• More streamlined project management: run commands without being in the same directory as your docker-compose.yml file with docker compose --project-name my-project stop . There’s also a new docker compose ls command that lists all your Compose projects.
• Docker Compose is now written in Go, like Docker itself, instead of being a separate Python utility. This allows Compose to reuse code from the main Docker CLI, creating more consistent behavior.

Incompatibilities with v1

Compose v2 is compatible with v1 in almost all use cases. You don’t need to modify your docker-compose.yml files or learn new commands, except for the change from docker-compose to docker compose. If you have your own tooling around the docker-compose command, you can change it to call docker compose instead.

While most migrations should be straightforward, Compose v2 does introduce a few breaking changes which could impact specific use cases:

• Containers are now created with hyphens in their names instead of underscores. This means a service called db within the app project will now create a container called app-db, instead of app_db. This could break scripts which expect the old container name format to be used. The change can currently be turned off by including the --compatibility flag with docker compose commands.
• docker compose build builds with BuildKit by default. BuildKit is Docker’s modern image build system which is capable of much faster builds. BuildKit is the recommended build system but it has a few remaining incompatibilities with the legacy build mechanism that could cause issues in some circumstances. You can disable BuildKit by setting the DOCKER_BUILDKIT=0 environment variable before you run docker compose commands.
• Some deprecated command flags have been removed. docker compose rm --all is not supported and the docker compose scale command is omitted in favor of docker compose up --scale. You’ll need to modify any scripts that rely on the docker-compose versions of these commands.

Upgrading on Linux

Although Compose now integrates with the Docker CLI, it’s not enabled by default in Docker Engine. You can install Compose v2 by adding it as a Docker CLI plugin. You must have Docker version v20.10.13 or later.

Update your package repositories and install docker-compose-plugin:

$ sudo apt update
$ sudo apt install docker-compose-plugin

Check the installation succeeded by retrieving Docker Compose’s version:

$ docker compose version
Docker Compose version v2.3.3

Now you can remove Docker Compose v1, unless you want to retain it to provide compatibility with legacy scripts. Both docker-compose (v1) and docker compose (v2) can co-exist if you need them to. If you’re removing v1, it’s normally found as a single binary at /usr/local/bin/docker-compose:

$ sudo rm /usr/local/bin/docker-compose

You could now set up a shell alias to redirect docker-compose to docker compose. This would let you keep using scripts that expect Compose v1, using your new v2 installation.

$ echo 'alias docker-compose="docker compose"' >> ~/.bashrc
$ source ~/.bashrc
$ docker-compose version
Docker Compose version v2.3.3

You’re now ready to start managing your containers with Compose v2.

Upgrading With Docker Desktop for Windows and Mac

Compose v2 is included with Docker Desktop versions 3.4 and later. v2 became the default Compose version in v4.4.2; if you’ve already taken the upgrade, you can use docker compose today.

v4.4.2 also aliases docker-compose to docker compose automatically. Compose v1 is inaccessible by default. You can disable this aliasing by running the docker-compose disable-v2 command or clearing the “Use Docker Compose v2” checkbox in Docker Desktop’s settings page. The docker-compose command will then revert to using Compose v1.

What’s Next?

Compose v1 remains supported for “high severity” security issues and bug fixes over the next six months. This support will be terminated in October 2022. v1 will then be deemed end of life so its use should be avoided. At this point, Docker Desktop will be updated to only support v2. You’ll have to use docker compose as the docker-compose aliasing will be removed. You’ll need to stay on an older release if you still require v1.

You can keep using v1 indefinitely by installing it as a standalone binary. You can find these published for Windows, Mac, and Linux on the project’s GitHub releases page. While these binaries will keep working indefinitely, most projects should aim to move to v2 in the near future. This will give you access to all the bug fixes, security updates, and new features in modern Compose v2 releases.

Summary

Docker Compose v2 is now the stable version of Docker Compose. Docker Desktop users will have been upgraded automatically. Linux installations of Docker Engine are catered for by the new docker-compose-plugin CLI plugin.

Support for Compose v1 ends in less than six months so you should check your scripts are compatible and then adopt v2 in the coming weeks. You’ll be able to use Compose within the docker CLI and benefit from the v2 features such as service profiles and the docker compose ls command.