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

Question

---

Note: this question was created BEFORE docker docs were updated (it was the reason they were updated - see this answer). Please do not post answers pointing out the docs on the differences :-)

---

I have been using docker-compose, but noticed there is also a docker compose (without the dash).
I have not been able to quickly determine the differences between the two forms by googling.

Anyone?

docker compose's help:

docker-compose's help:

Answer 1

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.

---

Update: since this question was asked, Linux installs have been updated by Docker to include compose v2 and docker-compose v1 is unlikely to receive any more updates.

Answer 2

Brandon Mitchell from docker's Captain Program 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

Answer 3

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/features-uses/#have-multiple-isolated-environments-on-a-single-host.

For posterity, the light description is:

Compose uses a project name to isolate environments from each other. ...

The default project name is the basename of the project directory. ...

The default project directory is the base directory of the Compose file. A custom value for it can be defined with the --project-directory command line option.

Answer 4

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.

Answer 5

There is more than just docker-compoe vs docker compose.

The docker-compose

Originally an external tool written in python. Its goal was to handle multiple containers creation and link them together. https://github.com/docker/compose/tree/0.0.1 It used fig.yml config file at first.

At some point it became a part of docker desktop and was shipped with it. https://docs.docker.com/desktop/previous-versions/archive-windows/

The config file was renamed from fig.yml to compose.yml at some point https://github.com/docker/compose/commit/2af7693e64010e11ba53f7fd923bb97f29b10063 and later to docker-compose.yml to better match binary name. It also supported compose.override.yml automatically loaded file and custom config files.

It took a lot of time but finally a new version rewritten in go lang replaced the old python version. It was called the docker-compose v2.

The docker compose plugin

Docker-compose was rewritten in go lang as a plugin for docker, thus the command is no longer an external binary but a docker sub-command.

It went back to the compose.yml config file (and compose.override.yml).

The config file versions

• Filename
  • fig.yml was expected. A warning was printed if fig.yaml was loaded instead.
  • compose.yml was the new config name
  • docker-compose.yml was introduced to better match binary name
  • compose.yml became again the preferred name as binary became a plugin of docker
• Content
  • New features were added and corresponding keywords - this long journey wouldn't be described here by me
  • The default network was changed at some point
  • The docker swarm project impacted syntax at some point - especially when looking at *deployment` and scaling
  • File /etc/hosts was originally a shared file mounted to every container and updated when new containers were started which allowed tools like dnsmasq to resolve container names https://github.com/docker/compose/pull/1375/files
  • In config version 2 the /etc/hosts was no longer updated breaking dnsmasq compatibility but instead new barely documented 127.0.0.11 (that is eleven at the end) was added to the networking which is an internal dummy DNS resolver
  • Convig version 3 removed support for extends keywors along with a few others https://docs.docker.com/compose/compose-file/compose-versioning/#version-3 However current version supports config file extending https://docs.docker.com/compose/multiple-compose-files/extends/ and it is still supported https://docs.docker.com/compose/compose-file/05-services/#extends
    • I hope that this keyword would remain supported as it is a very valuable option for complex projects when you wish something like kubernetes but in a lighweight form

Originally https://docs.docker.com/compose/

https://docs.docker.com/compose/history/

Answer 6

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

Answer 7

If you do not want to have changes, but desire the original legacy docker-compose functionality, also known as Compose standalone vs. Compose plugin, you can do the following:

# Run as root
VERSION=v2.12.2
curl -SL https://github.com/docker/compose/releases/download/$VERSION/docker-compose-linux-x86_64 -o /usr/local/bin/docker-compose
chmod a+x /usr/local/bin/docker-compose

# Test it
docker-compose

This allows you to e.g. keep using docker-compose in shell scripts.

Check versions on this page.

Answer 8

Another notable difference between the two is how the docker image tags are generated. For both commands, the image tag is concatenation of COMPOSE_PROJECT_NAME env var (project dir name if env var is not set) and name value from the compose file. For older docker-compose command the name is appended to COMPOSE_PROJECT_NAME with an underscore, but the newer docker compose command appends the two with a hyphen/dash -

Consider the compose file:

services:
  web:
    build: ./webapp

Assuming this compose file is present in the directory my_proj, the build command will generate different image tags.

docker-compose build web will generate docker.io/library/my_proj_web

docker compose build web will generate docker.io/library/my_proj-web

Answer 9

"docker-compose" is the old version v1.x "docker compose" is the new version v2.x If you are using ubuntu 22.04, use the following commands to install the "docker compose"

mkdir -p ~/.docker/cli-plugins/
curl -SL https://github.com/docker/compose/releases/download/v2.3.3/docker-compose-linux-x86_64 -o ~/.docker/cli-plugins/docker-compose

chmod +x ~/.docker/cli-plugins/docker-compose

docker compose version

Checkout the below link for further details to work with docker compose You may need to add keyword "sudo" for some commands to work without permission issues. https://www.digitalocean.com/community/tutorials/how-to-install-and-use-docker-compose-on-ubuntu-22-04