Blue Docker logo on a purple background

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.

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

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

Specification Changes

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 to 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 --project-name or -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.

Profile Photo for James Walker James Walker
James Walker is a contributor to How-To Geek DevOps. He is the founder of Heron Web, a UK-based digital agency providing bespoke software development services to SMEs. He has experience managing complete end-to-end web development workflows, using technologies including Linux, GitLab, Docker, and Kubernetes.
Read Full Bio »