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 update.

What’s new in v2?

Docker Compose v2 brings familiar Compose functionality to the standard docker CLI. Instead of interacting with a separate docker-compose binary, now you use docker compose. Compose is built 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 some new features that improve the user experience:

• You can use docker compose cp to copy files between your host and the containers.
• Cloud providers are valid targets, allowing you to docker compose up to deploy containers to Amazon ECS or Microsoft ACI.
• Service profiles are fully supported, making it easy to selectively include 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 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 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 do not need to modify your docker-compose.yml files or learn new commands, except for changing docker-compose a 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 big changes that could impact specific use cases:

• Containers are now created with hyphens in their names instead of underscores. This means a service called db within 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 commands
• docker compose build compiles with BuildKit by default. BuildKit is the modern Docker image build system that is capable of much faster builds. BuildKit is the recommended build system, but it has some remaining incompatibilities with the legacy build mechanism that could cause problems in some circumstances. You can disable BuildKit by setting the DOCKER_BUILDKIT=0 environment variable before executing docker compose commands
• Some deprecated command prompts have been removed. docker compose rm --all is not compatible and docker compose scale the command is omitted in favor of docker compose up --scale. You will have to modify any script that is based on the docker-compose versions of these commands.

Update on Linux

Although Compose now integrates with the Docker CLI, it is not enabled by default on the 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 coexist if you need them. If you’re removing v1, it’s usually found as a single binary at /usr/local/bin/docker-compose:

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

You can now configure a shell alias to redirect docker-compose a 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 versions 3.4 and later of Docker Desktop. v2 became the default version of Compose in v4.4.2; if you already took the update, you can use docker compose This day.

v4.4.2 also aliases docker-compose a docker compose automatically. Compose v1 is inaccessible by default. You can disable this alias by running the docker-compose disable-v2 command or by unchecking the “Use Docker Compose v2” checkbox on the Docker Desktop configuration page. the docker-compose The command will revert to using Compose v1.

Whats Next?

Compose v1 continues to support “high severity” security issues and bug fixes for the next six months. This support will end in October 2022. v1 will be considered end of life and should be avoided. At this point, Docker Desktop will be upgraded to only support v2. you will have to use docker compose As the docker-compose the alias will be removed. You will need to stay on a previous 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. While these binaries will continue to work 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 versions of Compose v2.

Summary

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

Support for Compose v1 ends in less than six months, so check to make sure your scripts are compatible and then adopt v2 in the coming weeks. You will be able to use Compose within the docker CLI and take advantage of v2 features such as service profiles and docker compose ls domain.