Migrating from Compose v1 to v2

--- title: Migrate to Compose v2 weight: 20 description: How to migrate from Compose v1 to v2 keywords: compose, upgrade, migration, v1, v2, docker compose vs docker-compose aliases: - /compose/compose-v2/ - /compose/cli-command-compatibility/ - /compose/migrate/ --- From July 2023, Compose v1 stopped receiving updates. It’s also no longer available in new releases of Docker Desktop. Compose v2, which was first released in 2020, is included with all currently supported versions of Docker Desktop. It offers an improved CLI experience, improved build performance with BuildKit, and continued new-feature development. ## How do I switch to Compose v2? The easiest and recommended way is to make sure you have the latest version of [Docker Desktop](/manuals/desktop/release-notes.md), which bundles the Docker Engine and Docker CLI platform including Compose v2. With Docker Desktop, Compose v2 is always accessible as `docker compose`. For manual installs on Linux, you can get Compose v2 by either: - [Using Docker's repository](/manuals/compose/install/linux.md#install-using-the-repository) (recommended) - [Downloading and installing manually](/manuals/compose/install/linux.md#install-the-plugin-manually) ## What are the differences between Compose v1 and Compose v2? ### `docker-compose` vs `docker compose` Unlike Compose v1, Compose v2 integrates into the Docker CLI platform and the recommended command-line syntax is `docker compose`. The Docker CLI platform provides a consistent and predictable set of options and flags, such as the `DOCKER_HOST` environment variable or the `--context` command-line flag. This change lets you use all of the shared flags on the root `docker` command. For example, `docker --log-level=debug --tls compose up` enables debug logging from the Docker Engine as well as ensuring that TLS is used for the connection. > [!TIP] > > Update scripts to use Compose v2 by replacing the hyphen (`-`) with a space, using `docker compose` instead of `docker-compose`. ### Service container names Compose generates container names based on the project name, service name, and scale/replica count. In Compose v1, an underscore (`_`) was used as the word separator. In Compose v2, a hyphen (`-`) is used as the word separator. Underscores aren't valid characters in DNS hostnames. By using a hyphen instead, Compose v2 ensures service containers can be accessed over the network via consistent, predictable hostnames. For example, running the Compose command `-p myproject up --scale=1 svc` results in a container named `myproject_svc_1` with Compose v1 and a container named `myproject-svc-1` with Compose v2. > [!TIP] > > In Compose v2, the global `--compatibility` flag or `COMPOSE_COMPATIBILITY` environment variable preserves the Compose v1 behavior to use underscores (`_`) as the word separator. As this option must be specified for every Compose v2 command run, it's recommended that you only use this as a temporary measure while transitioning to Compose v2. ### Command-line flags and subcommands Compose v2 supports almost all Compose V1 flags and subcommands, so in most cases, it can be used as a drop-in replacement in scripts. #### Unsupported in v2 The following were deprecated in Compose v1 and aren't supported in Compose v2: * `docker-compose scale`. Use `docker compose up --scale` instead. * `docker-compose rm --all` #### Different in v2 The following behave differently between Compose v1 and v2: | | Compose v1 | Compose v2 | |-------------------------|------------------------------------------------------------------|-------------------------------------------------------------------------------| | `--compatibility` | Deprecated. Migrates YAML fields based on legacy schema version. | Uses `_` as word separator for container names instead of `-` to match v1. |

Compose v1 is no longer receiving updates, so migration to v2 is recommended. Compose v2 is included with Docker Desktop and offers improvements like a better CLI experience and build performance. The key difference is the command syntax: `docker compose` instead of `docker-compose`. Also, Compose v2 uses hyphens instead of underscores in container names, though compatibility mode can temporarily preserve the old behavior. Most v1 commands and flags are supported in v2, with a few exceptions like `docker-compose scale` and `docker-compose rm --all`.