Docker Compose v2 Explained: What Changed & How to Migrate

Docker Compose v2 is the current version of the Compose tool, replacing the older v1 that was written in Python. The main change is that v2 is a Go-based plugin integrated directly into the Docker CLI, so you use docker compose (with a space) instead of the standalone docker-compose command, and it brings faster performance, better compatibility with the Docker engine, and a unified command structure. Migrating is straightforward: install the v2 plugin, update your CI scripts and aliases to use the new syntax, and your existing docker-compose.yml files will work as-is in nearly all cases.

Background: Why Compose v2 Exists

Docker Compose was introduced in 2014 as a Python tool to define and run multi-container applications with a single YAML file. For years, the command docker-compose was a separate binary that you had to install alongside Docker. As Docker evolved, the Compose specification was decoupled from the implementation, and in 2020 Docker announced a rewrite in Go, which became Compose v2. The new version was first released as a plugin for the Docker CLI, then became the default in Docker Desktop and Docker Engine 20.10+.

The key motivation was to make Compose a first-class part of the Docker experience, not an add-on. Go gives better startup time and lower memory usage than Python, and being a plugin means it updates with Docker itself, reducing version mismatch issues. The docker compose command also supports the newer Docker features like docker compose watch and better integration with docker buildx.

What Actually Changed in v2

• Command syntax: docker-compose (hyphen) becomes docker compose (space). The old command still works if you install the standalone binary, but it is deprecated.
• Implementation language: Python to Go, which means faster execution and no need for a separate Python runtime.
• Compose file format: v2 still reads the same docker-compose.yml files, but it fully supports the Compose Specification (version-agnostic). You can drop the version: key entirely; it is ignored if present.
• New subcommands: docker compose watch for live reload, docker compose cp to copy files to/from containers, and docker compose ls to list running projects.
• Environment handling: Better support for .env files, including interpolation and defaults, and the --env-file flag works more predictably.
• Networking and volumes: Improved handling of network and volume names, with less chance of name collisions when multiple projects run.

How to Migrate from v1 to v2

1. Install the v2 plugin. On Docker Desktop, it is included by default. On Linux, you can install the plugin from the Docker repository or download the binary to ~/.docker/cli-plugins/docker-compose. Verify with docker compose version.
2. Update your scripts and aliases. Replace every docker-compose command with docker compose. If you have many scripts, a simple alias docker-compose='docker compose' works for interactive shells, but for CI you need to edit the actual commands.
3. Test your YAML files. Run docker compose config to validate. Most v1 files work unchanged, but watch for deprecated keys like version: (ignored) and depends_on with condition: service_healthy (still supported).
4. Check for removed features. A few v1 flags are gone, like --compatibility (no longer needed) and some obscure environment variable overrides. Consult the release notes if you use them.
5. Update your CI pipelines. GitHub Actions, GitLab CI, and Jenkins images often have the old binary; change the image or install the plugin in the job.

Common Problems and How to Fix Them

The most common issue after migration is the docker-compose: command not found error, which simply means the standalone binary is not installed. You can either install it (but that defeats the purpose) or update your script to use docker compose. Another frequent problem is that docker compose may not be available on older Docker engines; ensure you have Docker Engine 20.10 or later.

Some users see version is obsolete warnings. That is harmless; v2 ignores the version key, so you can remove it. If you use docker-compose.override.yml, v2 still reads it, but the merge behavior is slightly different for lists like ports and volumes – v2 replaces the list instead of appending. This is a rare breaking change; check your overrides.

Another gotcha: v2 treats the project name differently. By default, it uses the directory name, but if you have hyphens or uppercase, it sanitizes them. You can force a name with docker compose -p myproject or the name: key in the YAML.

Comparing v1 and v2: What You Gain

Performance is the most tangible gain. v2 starts in milliseconds rather than hundreds of milliseconds, and build operations are faster because they use BuildKit by default. You also get better output with colored logs and a cleaner docker compose ps table.

Feature-wise, v2 adds docker compose watch, which is a huge productivity boost for development – it automatically syncs files and rebuilds containers when you save. The docker compose cp command is handy for debugging. v2 also has improved support for GPU resources, profiles (to selectively start services), and the include feature to split your Compose file into multiple files.

The old v1 is still maintained for legacy reasons, but it is no longer the default and will not receive new features. Docker has stated that v1 is deprecated, so migrating is the only forward path.

Costs and Licensing

Docker Compose v2 is open source under the Apache 2.0 license, so there is no cost to use it. The Docker Desktop application that bundles it is free for small businesses (under 250 employees and under $10 million in revenue) and for personal use; larger companies need a paid subscription. The Compose plugin itself, however, is free to use on any Linux server with Docker Engine, regardless of company size.

If you are migrating, there is no additional cost beyond the time to update your scripts. The YAML files remain the same, so you do not need to rewrite your application definitions.

Safety and Best Practices

When migrating, do not run v1 and v2 simultaneously on the same project – they may conflict over container names and networks. Stop all containers with docker compose down (or v1 equivalent) before switching. Also, always test in a non-production environment first.

For production, avoid using docker compose up -d without pinned image tags; use specific versions in your YAML. And remember that docker compose is not a replacement for orchestrators like Kubernetes – it is meant for single-host development and simple deployments. For multi-host, use Docker Swarm or Kubernetes.

One misconception is that v2 requires a new YAML format. That is false – v2 reads the same files as v1. The Compose Specification is a vendor-neutral standard, and v2 implements it fully. So you can migrate without touching your docker-compose.yml content.

Frequently Asked Questions

Is docker-compose still supported?

The old v1 binary is still available for download, but it is deprecated and will not receive new features. Docker recommends using docker compose v2. If you have scripts that rely on the old command, you can install the standalone v2 binary that also responds to docker-compose, but the recommended path is to update your scripts.

Do I need to change my docker-compose.yml file?

In most cases, no. v2 is backward compatible with the Compose file format. You can remove the version: line if you want, but it is not required. However, if you use features that were deprecated in the spec, you may see warnings – check docker compose config to see them.

Why does docker compose say ‘command not found’?

That means the v2 plugin is not installed. On Docker Desktop it is included, but on Linux you need to install it manually. Download the binary from the Docker GitHub releases and place it in ~/.docker/cli-plugins/ or /usr/local/lib/docker/cli-plugins/, then make it executable.

Can I use v2 with Docker Swarm?

Yes, docker compose can deploy to a Swarm cluster using docker stack deploy, but the Compose file must be in the v3 format (or the spec) and cannot use some v2-only features like build. For local development with Swarm, you can still use docker compose up on a single node.

What is the difference between docker compose and docker-compose?

The first is the v2 plugin command, the second is the legacy v1 standalone binary. They are functionally similar, but v2 is faster, integrates with the Docker CLI, and is the current default. The space vs. hyphen is the key difference in typing.

Will my CI pipeline break after migration?

It might, if it calls docker-compose. You need to update the commands to docker compose and ensure the runner has the plugin installed. Most CI images (like GitHub Actions’ docker/compose action) already use v2, but check your specific setup.

Related

• Recover Notes from Mac: Full Guide
• Keep Sensitive AI Data Under Control in Hybrid Cloud
• Run a Gym Codes: What They Are & How to Use Them