How to upgrade to Docker Compose v2

After almost a year in beta, Docker Compose v2 is generally available as a stable version of the container management tool. 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 familiar Compose features to everyday life docker CLI. Instead of interacting with another docker-compose binary you are now using docker compose. Compose is integrated with Docker.

You can replace the 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, allowing you docker compose up to deploy containers on Amazon ECS or Microsoft ACI.
• Service profiles are fully supported, making it easy to selectively include containers in a stack.
• Simplified project management: execute commands without being in the same directory as your docker-compose.yml folder with docker compose --project-name my-project stop . There is 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 core Docker CLI code, creating more consistent behavior.

Incompatibilities with v1

Compose v2 is compatible with v1 in almost all use cases. You do not need to modify your docker-compose.yml files or learn new commands, with the exception of changing docker-compose à docker compose. If you have your own tools around the docker-compose command, you can change it to call docker compose Instead.

While most migrations should be straightforward, Compose v2 introduces a few breaking changes that might impact specific use cases:

• Containers are now created with hyphens in their names instead of underscores. It means a service called db within the app project will now create a container called app-dbinstead of app_db. This could break scripts that expect the old container name format to be used. The change can currently be disabled by including the --compatibility flag with docker compose orders.
• docker compose build built with BuildKit by default. BuildKit is Docker's modern imaging system, capable of building builds much faster. BuildKit is the recommended build system, but there are still some incompatibilities with the legacy build mechanism that could cause issues under certain circumstances. You can disable BuildKit by setting the DOCKER_BUILDKIT=0 environment variable before running docker compose orders.
• Some obsolete 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 will 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 is 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

Verify that the installation was successful by retrieving the Docker Compose version:

$ docker compose version Docker Compose version v2.3.3

You can now remove Docker Compose v1, unless you want to keep it for compatibility with legacy scripts. Both docker-compose (v1) and docker compose (v2) can co-exist if you need them. If you remove v1 it is normally found as a single binary on /usr/local/bin/docker-compose:

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

You can now configure a shell alias to redirect docker-compose à docker compose. This would allow you to continue 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 are now ready to start managing your containers with Compose v2.

Upgrade with Docker Desktop for Windows and Mac

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

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

And after?

Compose v1 remains supported for security issues and "high severity" bug fixes for the next six months. This support will end in October 2022. v1 will then be considered end of life, so its use should be avoided. At this point, Docker Desktop will be updated to only support v2. You will need to use docker compose such as docker-compose aliasing will be removed. You will have to stick to an older version if you still need v1.

You can continue to use v1 indefinitely by installing it as a standalone binary. You can find them released for Windows, Mac, and Linux on the project's GitHub releases page. Although these binaries will continue to work indefinitely, most projects should aim to upgrade to v2 in the near future. This will give you access to all bug fixes, security updates, and new features in modern versions of Compose v2.

In this section:

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 supported by the new docker-compose-plugin CLI plug-in.

Support for Compose v1 ends in less than six months. You should therefore check that your scripts are compatible, then adopt v2 in the coming weeks. You will be able to use Compose in the docker CLI and benefit from v2 features such as service profiles and docker compose ls ordered.