Docker Compose is an immensely popular tool for working with containers. Whereas the ordinary
docker CLI interacts with one container at a time,
docker-compose lets you control multiple containers in aggregate.
Compose currently exists as a standalone project that’s distributed independently of Docker. If you want to use Compose, you’ll need to download it separately. Many users end up grabbing the binary directly, as OS package managers often lag behind, even if they offer the latest Docker version.
Docker Compose v2 was announced at DockerCon 2021. It promises big changes to the Compose experience by integrating it into the
docker CLI. v2 also comes with new convenience features to help you manage your container stacks.
The New “docker compose” Command
Docker Compose v2 brings Compose functionality into Docker itself. You’ll be able to use Compose wherever the latest Docker CLI is installed, no extra steps required. Underneath, Docker continues to use the features provided by the Compose project.
docker-compose commands should map directly to their new
docker compose counterparts. In most cases, you can drop the dash with no further changes required.
docker compose supports almost all the Compose v1 sub-commands and flags, although a minority will not be implemented.
Compose v2 will still support invocation via the
docker-compose binary. Existing workflow scripts should keep working, even if you don’t immediately update them to use
docker compose. In the long-term, it’s likely that most authors will switch over to the new form instead.
Experimenting With Docker Compose v2
Compose v2 is currently in beta. Although it remains in development, the new binary is already shipping with Docker Desktop for Windows and Mac. Desktop v3.4 added support for the
docker compose commands, so chances are you can already use it today. The Linux packages will be updated later in the year; a manual installation script is available in the meantime.
docker-compose command may currently invoke v1 or v2, defaulting to v1. The option is being automatically turned on for a subset of users; it will eventually launch v2 for all.
You can manually switch
docker-compose between v1 and v2 by running
docker-compose disable-v2 or
docker-compose enable-v2. This lets you maintain compatibility with any existing Compose files which don’t work with v2.
docker compose commands will always use v2.
Bringing Compose functionality to the Docker CLI has necessitated changes to the Compose spec. This now distinguishes between command implementations and the
docker-compose.yml YAML format.
The revised approach provides new opportunities to integrate additional features. Experimental implementations can be provided more quickly and the Compose team is better equipped to add community proposals. The CLI is more decoupled from the YAML file format, so alternative implementations (like
docker compose) are a possibility.
Beyond the CLI, the existence of the Composer spec allows cloud providers to implement Compose functionality too. You can now run
docker compose up against a cloud-based Docker context to launch your app in production. Docker comes with built-in support for Amazon ECS and Microsoft ACI environments.
Internally, Compose v2 uses Buildkit by default for faster builds. Overall performance should be quicker as more tasks run in parallel, reducing processing times.
New Features In v2
The switch from
docker compose isn’t the only change in v2. There are also new features that affect how you interact with your container stacks.
One limitation of Compose v1 is its approach to project names. When you run
docker-compose up -d, Compose prepends the project name to each container’s service name. This ensures all the containers are grouped together.
v1 infers the project name from the name of your working directory. You can manually choose a different name by setting the
COMPOSE_PROJECT_NAME environment variable.
v2 simplifies this by adding a CLI flag to set the project name. Add
-p to ignore the working directory’s name, without altering the environment. Manually setting the project name lets you combine containers from multiple working directories into one stack, or start multiple instances of a container stack.
Another new v2 feature lets you list all Compose stacks on your system. The
docker compose ls command provides a table of project names and their status (running or stopped). This complements the
docker compose ps command which gives the statuses of containers in a stack.
Compose v2 also adds support for
docker compose cp. This command works similarly to
docker cp and lets you copy files in and out of your containers:
docker cp my-container local-file.txt /path/to/container/file.txt
Docker Compose v2 is a substantial upgrade that brings improved convenience to the container management tool. Integrating Compose into the main Docker CLI means it’s available wherever Docker is. This makes it more accessible and easier to get started with.
Compose v2 also brings some extra utility commands to make it easier to work with different stacks and containers. You get improved visibility into what’s running on your system. While it’s still in beta at the time of writing, Windows and Mac users can use v2 today, while Linux users can download the latest build from GitHub.