Compose v2: Migration and Compatibility Considerations

For Compose v2, the [Environment variables](/manuals/compose/how-tos/environment-variables/_index.md) section covers both [precedence](/manuals/compose/how-tos/environment-variables/envvars-precedence.md) as well as [`.env` file interpolation](/manuals/compose/how-tos/environment-variables/variable-interpolation.md) and includes many examples covering tricky situations such as escaping nested quotes. Check if: - Your project uses multiple levels of environment variable overrides, for example `.env` file and `--env` CLI flags. - Any `.env` file values have escape sequences or nested quotes. - Any `.env` file values contain literal `$` signs in them. This is common with PHP projects. - Any variable values use advanced expansion syntax, for example `${VAR:?error}`. > [!TIP] > > Run `docker compose config` on the project to preview the configuration after Compose v2 has performed interpolation to verify that values appear as expected. > > Maintaining backwards compatibility with Compose v1 is typically achievable by ensuring that literal values (no interpolation) are single-quoted and values that should have interpolation applied are double-quoted. ## What does this mean for my projects that use Compose v1? For most projects, switching to Compose v2 requires no changes to the Compose YAML or your development workflow. It's recommended that you adapt to the new preferred way of running Compose v2, which is to use `docker compose` instead of `docker-compose`. This provides additional flexibility and removes the requirement for a `docker-compose` compatibility alias. However, Docker Desktop continues to support a `docker-compose` alias to redirect commands to `docker compose` for convenience and improved compatibility with third-party tools and scripts. ## Is there anything else I need to know before I switch? ### Migrating running projects In both v1 and v2, running up on a Compose project recreates service containers as needed. It compares the actual state in the Docker Engine to the resolved project configuration, which includes the Compose YAML, environment variables, and command-line flags. Because Compose v1 and v2 [name service containers differently](#service-container-names), running `up` using v2 the first time on a project with running services originally launched by v1, results in service containers being recreated with updated names. Note that even if `--compatibility` flag is used to preserve the v1 naming style, Compose still needs to recreate service containers originally launched by v1 the first time `up` is run by v2 to migrate the internal state. ### Using Compose v2 with Docker-in-Docker Compose v2 is now included in the [Docker official image on Docker Hub](https://hub.docker.com/_/docker). Additionally, a new [docker/compose-bin image on Docker Hub](https://hub.docker.com/r/docker/compose-bin) packages the latest version of Compose v2 for use in multi-stage builds. ## Can I still use Compose v1 if I want to? Yes. You can still download and install Compose v1 packages, but you won't get support from Docker if anything breaks. >[!WARNING] > > The final Compose v1 release, version 1.29.2, was May 10, 2021. These packages haven't received any security updates since then. Use at your own risk. ## Additional Resources - [docker-compose v1 on PyPI](https://pypi.org/project/docker-compose/1.29.2/) - [docker/compose v1 on Docker Hub](https://hub.docker.com/r/docker/compose) - [docker-compose v1 source on GitHub](https://github.com/docker/compose/releases/tag/1.29.2)

Compose v2 has improved environment variable handling. Switching to `docker compose` is recommended, though Docker Desktop maintains the `docker-compose` alias. Running `up` in v2 after using v1 may recreate service containers due to naming differences. Compose v2 is included in the official Docker image and available as a separate image for multi-stage builds. Compose v1 remains available but is unsupported and hasn't received security updates since May 2021. Resources for Compose v1 are provided.