Skip to content

Docker Compose vs. docker-compose: Clearing Up the Confusion

Docker Linux Shamsher Haider BigData

Did you try to follow some online tutorial to fire up your docker-compose.yaml and ended up with strange python and “chunked” errors? You probably mixed up “docker compose” with “docker-compose” (found in old tutorials) and its a shame that there are very few clear explanations on the internet when you try debugging it. This article will very quickly solve the mystery for you.

Understanding Docker Compose

Originally, Docker Compose was a separate tool called “docker-compose“. It offered a user-friendly way to define and manage multi-container applications through a YAML file (usually named docker-compose.yml). This file specifies the services (containers) required for the application, their configurations, dependencies, and how they interact with each other.

However, with Docker version 19.03 and later, Docker Compose functionality was integrated directly into the Docker engine. Now, you can manage your multi-container applications using the "docker compose" command. This streamlined approach simplifies the workflow, but it also introduces the potential for confusion with the older “docker-compose” command.

Differentiating the Commands

Here’s what separates “docker compose” from “docker-compose”:

  • Installation: “docker-compose” was a separate tool requiring its own installation. “docker compose” comes pre-installed with Docker versions 19.03 and later.
  • Availability: “docker-compose” is only available on older Docker versions (pre-19.03). “docker compose” works on all Docker versions (19.03 onwards).
  • Functionality: While unlikely, there might be slight feature discrepancies between the two commands depending on the Docker version used. It’s always best to refer to the official documentation for the specific version you’re using.

Examples in Action

Let’s see how these commands work in practice. Here’s a basic docker-compose.yml file defining a simple web application with a Node.js server and a MySQL database:

version: "3.8"

    image: node:16-alpine
      - "5000:5000"
      - ./app:/app
    image: mysql:8.0
      MYSQL_ROOT_PASSWORD: mypassword
      - mysql-data:/var/lib/mysql
  mysql-data: {}

Using docker compose (Docker 19.03+)

docker compose up -d

This command will start all services defined in the docker-compose.yml file in detached mode (background).

Using docker-compose (pre-Docker 19.03)

docker-compose up -d

This achieves the same outcome as the previous command, but only if you have “docker-compose” installed separately.

Impact of Confusion

Mixing up these commands can lead to unexpected behavior. Here’s what might happen:

  • Command not found: If you’re using Docker versions 19.03 and later and try “docker-compose”, you’ll get a “command not found” error as this command is no longer available.
  • Incorrect behavior: Even if “docker-compose” is somehow available, it might not work as expected with newer Docker versions due to potential feature differences.

Best Practices and Recommendations

To avoid confusion, follow these best practices:

  • Check your Docker version: Knowing your Docker version helps determine the appropriate command to use.
  • Standardize on “docker compose”: This ensures consistency and future-proofing your workflows, especially with newer Docker versions.
  • Refer to official documentation: The Docker documentation provides the latest information on available commands and their functionalities based on your Docker version (


Understanding the difference between “docker compose” and “docker-compose” is crucial for managing multi-container applications effectively. By following the recommendations above, you can avoid confusion and ensure your Docker workflows run smoothly. Remember, with newer Docker versions, “docker compose” is the way to go! While Docker Compose offers a powerful approach, alternative tools like Docker Swarm or Kubernetes exist for managing complex deployments with a larger number of containers. Do explore the official Docker documentation and tutorials for in-depth learning on Docker Compose and multi-container application development.