Difference between "docker compose" and "docker-compose"

The docker compose (with a space) is a newer project to migrate compose to Go with the rest of the docker project. This is the v2 branch of the docker/compose repo. It's been first introduced to Docker Desktop users, so docker users on Linux didn't see the command. In addition to migrating to Go, it uses the compose-spec, and part of the rewrite may result in behavior differences.

The original python project, called docker-compose, aka v1 of docker/compose repo, has now been deprecated and development has moved over to v2. To install the v2 docker compose as a CLI plugin on Linux, supported distribution can now install the docker-compose-plugin package. E.g. on debian, I run apt-get install docker-compose-plugin.

Brandon Mitchell from docker replied to the github issue I opened on this as follows:

The docker/compose-cli project is in an in-between state, where it's not available in upstream releases of the docker-cli Linux packages, but is being included in Docker Desktop. The documentation pages normally follow what's in the docker/cli, so having this released to Desktop early puts the documentation in a difficult position. I'm going to raise this issue with the Docker team to see how they'd like to handle it.

Update: from docker github issue:

gtardif commented 2 days ago

compose command reference doc is now live

new docker-compose command reference

Quote from https://docs.docker.com/compose/#compose-v2-and-the-new-docker-compose-command

Compose V2 and the new docker compose command
    Important
    The new Compose V2, 
which supports the compose command as part of the Docker CLI, is now available.

    Compose V2 integrates compose functions into the Docker platform, 
continuing to support most of the previous docker-compose features and flags. 
You can run Compose V2 by replacing the hyphen (-) with a space, 
using docker compose, instead of docker-compose.

If it not yet included in the docker installation, docker compose can be installed on Linux as CLI plugin.

COMPOSE_VERSION=$(curl -s https://api.github.com/repos/docker/compose/releases/latest | jq -r '.tag_name')

DOCKER_CONFIG=${DOCKER_CONFIG:-$HOME/.docker}
mkdir -p $DOCKER_CONFIG/cli-plugins
curl -SL https://github.com/docker/compose/releases/download/$COMPOSE_VERSION/docker-compose-linux-x86_64 -o $DOCKER_CONFIG/cli-plugins/docker-compose
chmod +x $DOCKER_CONFIG/cli-plugins/docker-compose

See https://docs.docker.com/compose/cli-command/#installing-compose-v2

In addition to what has been already said here, I have noticed an important difference between the two.

In our setup, the docker-compose.yml file is located in a template folder. This way we can run multiple instances of the same project based on the same template. The local instance has its own folder with its own .env file (and also its own volumes).

There is also a template .env file in the template folder : copied and adapted to the instance folder using a script.

In order to work, the docker-compose.yml file looks like this, in the template folder :

version: "3"

services:

  wordpress:
    image: wordpress
    container_name: "${COMPOSE_PROJECT_NAME}_wordpress"
    env_file:
      - ${PWD}/.env
 ...

And the local instance .env file :

# compose file location
COMPOSE_FILE=../templateFolder/docker-compose.yml

# this instance name
COMPOSE_PROJECT_NAME=foo

In this context :

• with docker-compose, the .env file is read in the instance location, which is expected
• with docker compose, the .env file is read in the template location !

To override this, we had to rename the template .env file into dotEnv.

This behavior is very lightly described here : https://docs.docker.com/compose/#multiple-isolated-environments-on-a-single-host