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

Summary

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.