Docker Community Forums

Share and learn in the Docker community.

Docker/compose vs docker/compose-cli

This is an inherently hard problem to Google, so please hit me with links if I missed something (I searched as hard as I could).

What is the difference between docker/compose-cli and docker/compose? (I’m going to refer to them by their Github names because that’s the least confusing way.) Here’s what I’ve got so far:



  • Go
  • downloadable on its Github release page as a binary just called “docker”?
  • on Docker Desktop for Mac, is invoked with docker compose?
  • reads docker-compose.yml files
  • Github README says it can deploy to cloud environments (Azure, ECS)

So is docker/compose-cli the successor to docker/compose? It seems it can’t deploy locally? I get an error

$ docker compose up
Command "compose up" not available in current context (default)

Besides the documentation built into the CLI, I can find no documentation about docker/compose-cli. The docs on the website refer to docker-compose aka docker/compose, but call it Docker Compose. It has no mention of deploying docker-compose.yml manifests to cloud providers (except Swarm).

Did Docker just create two products that are all-but-identically named, read the same docker-compose.yml manifest, both come with Docker Desktop, have many of the same CLI subcommands and flags, but whose deployment targets are disjoint sets? That don’t mention their relationship to one another? What the hell is going on here?

1 Like

Found this

If you set the Compose file version to 3.8 or later, you can use the same Compose file for local deployment using docker-compose . Custom extensions will be ignored in this case.

That’s the only piece of information that hints to the difference between them.

Opened a bug as well

Starting with docker version 19.03.0, it is possible to extend the docker command with subcommands. It is an experimental feature called cli-plugin. docker/compose-cli is one of those cli-plugins, once installed its fuctionality will be available as a subcommand to the docker command.

In order to make it work, experimental features need to be specificly enabled: either temporary on the shell by setting DOCKER_CLI_EXPERIMENTAL=enabled or permanently by adding the same command to your .bashrc or even better by enabling experimental features in /etc/docker/daemon.json

Docker app is another one of those cli-plugins:, which is a Cloud Native application packaging framework.

docker-compose started as a standalone third party application (initaly called fig) and was incorparated into the docker ecosystem. If docker (the project/company) would’ve created it from the scratch, it would high likely be written in go, like the rest of the docker components…

I would love it, if the cli-plugin would be a drop-in replacement for docker-compose :slight_smile: Didn’t use it so far, so can’t say wether it is or not.

I guess everything started with this gist: and two github issues (or vice-versa).

The docker cli is used when managing individual containers on a docker engine. … The docker-compose cli can be used to manage a multi-container application. It also moves many of the options you would enter on the docker run cli into the docker-compose. yml file for easier reuse.

Thank you for the information.

I’m glad to see this.


Interesting, but this does not appear to be the case. I can’t find a separate binary on my system, and the binary on compose-cli's Github Releases page appears to just be the regular old docker binary. Maybe this was the case previously? It’s also not listed in docker plugin list:

$ docker plugin list
ID                  NAME                DESCRIPTION         ENABLED
$ docker compose
Docker Compose

  docker compose [command]

Still doesn’t explain why there are two commands named almost exactly the same and whose target deployment platforms don’t intersect :stuck_out_tongue:

I’m aware of what docker-compose is, been using it for years :slight_smile: I don’t know what docker compose is WRT to docker-compose.

Neat. But still not sure how that turned into a thing that does not replicate the core functionality of docker-compose: deploying a set of containers to local docker.

docker plugin != cli-plugin.

Though, the supposed cli-plugin turned out to be an ordinary binary placed in /usr/local/bin/docker, acompanied by symlink from /usr/bin/docker to /usr/local/bin/com.docker.cli. Seems like the new binary wrapps the old binary… Indeed very confusing. The binary in /usr/local/bin/docker appears to have precedence over the default binary in /usr/bin/docker.

I would have expected a cli-plugin in my ~/.docker/cli-plugins folder. I have used the cli-plugin “docker app” in the past, which worked as advertised.

I had to relogin in order for docker compose to work.

me@swarm1:~/.docker$ docker compose
Docker Compose

  docker compose [command]

Available Commands:
  convert     Converts the compose file to a cloud format (default: cloudformati                                                                                        on)

  -h, --help   help for compose

Global Flags:
      --config DIRECTORY   Location of the client config files DIRECTORY (defaul                                                                                        t "/home/me/.docker")
  -c, --context string     context
  -D, --debug              Enable debug output in the logs
  -H, --host string        Daemon socket(s) to connect to

Use "docker compose [command] --help" for more information about a command.

update: I completly missed your point. Indeed, it does not allow to deploy localy. Turns out it is just a fency feature for azure and aws users and not a drop-in replacement for docker-compose. It feels wrong that this subcomand is called compose… wouldn’t cloud be the better fittings subcommand?!

Turns out it is just a fency feature for azure and aws users and not a drop-in replacement for docker-compose. It feels wrong that this subcomand is called compose … wouldn’t cloud be the better fittings subcommand?!

I wouldn’t mind if it were called docker compose still, if it still supported local deploys. It’s sort of similar. (Though using docker-compose.yml to deploy production services seems like a not great idea.)

I don’t want to be a jerk here, but it seems to me either Docker:

  1. created a new tool for deploying to cloud providers and called it docker compose being somehow unaware that an existing tool called docker-compose exists (despite being able to read its manifest file format); or

  2. docker compose is indeed intended to replace docker-compose, but they started by implementing new features instead of supporting the old, and despite the fact that compose-cli is currently v1.x, it is not backwards-compatible with docker-compose in any way (except the manifest file format and some of the CLI syntax)

I agree, unless it allows deployments to the default context (=docker.sock) and ssh based contexts, the name compose is ambigous as hell.

If the target environment is ECS, then why not? Swarm stacks leverage the compose file format as well, and for “simple things” it is “kind of enough” for productive deployment. Though, you will always have to put in extra effort when building your images, as init containers and side cars are not existing (fun fact: podman supports the pod concecpt even without k8s)

Btw., the default clli-plugins are located in /usr/libexec/docker/cli-plugins/ on Ubuntu.

Anyway, thank you for bringing this topic up. I learned something new :slight_smile:

Just to be clear: I’m not saying it’s a terrible idea an you should never do it, just that it’s not great as far as production deployment tools go. Hard to quantify why exactly, but after using docker-compose for local dev and some CI testing, I wouldn’t trust it to deploy my production workloads.

That said, docker compose is evidently a 100% new code base, so who knows, maybe it rocks :stuck_out_tongue: