🚨 Docker Error Guide: 'docker-compose: command not found' — Compose v1 vs the v2 Plugin

Overview

You run a familiar command and the shell simply cannot find it:

bash: docker-compose: command not found

This is almost never a broken Docker installation. It is the result of Docker Compose moving from a standalone Python binary (Compose v1, invoked as docker-compose) to a Go-based Docker CLI plugin (Compose v2, invoked as docker compose — a space, not a hyphen). On modern installs the hyphenated command does not exist unless you explicitly add a compatibility shim, so any script or muscle-memory that calls docker-compose fails.

Symptoms

• docker-compose up returns command not found, but docker compose up works fine.
• CI pipelines that were green for years suddenly fail on the docker-compose step after a runner image upgrade.
• docker compose version prints Docker Compose version v2.x, yet docker-compose version errors.
• A Makefile or shell script that hardcodes docker-compose breaks on a fresh host while working on an older one.
• which docker-compose returns nothing, while which docker resolves correctly.

Common Root Causes

• Only the v2 plugin is installed. Docker Desktop and recent docker-ce packages ship the Compose v2 plugin (docker compose) and do not install the docker-compose v1 binary.
• Compose v1 was never installed. On a minimal server you may have docker (the Engine) but no Compose component at all.
• The v1 binary is not on PATH. A manual install dropped docker-compose in /usr/local/bin or ~/.docker/cli-plugins, but that directory is not in the shell’s PATH.
• Compose v1 reached end of life. Compose v1 stopped receiving updates and was removed from many distro repos, so package upgrades quietly dropped it.
• The Compose plugin package is missing. The Engine is installed but docker-compose-plugin (or Docker Desktop) is not, so neither the space nor the hyphen form exists.

Diagnostic Workflow

First confirm which form of Compose, if any, is available. The v2 plugin uses a space:

docker compose version
docker-compose version

If the first works and the second does not, you are simply calling the retired name. Confirm the plugin is registered with the Docker CLI:

docker info | grep -iA2 'Plugins'
ls -l /usr/lib/docker/cli-plugins/ /usr/libexec/docker/cli-plugins/ ~/.docker/cli-plugins/ 2>/dev/null

The docker-compose executable, if present, must be on PATH:

which docker-compose
echo "$PATH"

Validate that your Compose file itself parses under v2 before troubleshooting the command name further:

docker compose config

A minimal file to test against — note there is no version: key, which is obsolete in Compose v2:

services:
  web:
    image: registry.example.com/myapp:1.4.2
    ports:
      - "8080:8080"

Example Root Cause Analysis

A team migrated their build to a new Ubuntu 24.04 GitHub Actions runner. The pipeline step docker-compose -f docker-compose.ci.yml up -d had worked unchanged for two years. On the new runner it failed immediately with docker-compose: command not found.

Investigation showed the runner image had upgraded to docker-ce with the docker-compose-plugin package but without the legacy docker-compose standalone binary. Running docker compose version on the runner printed Docker Compose version v2.29.1, confirming Compose was present — just under the plugin name.

The root cause was a hardcoded reference to the v1 command name in a tool that no longer ships it. The fix was to change the pipeline step to docker compose -f docker-compose.ci.yml up -d. Because Compose v2 is a drop-in replacement for the common subcommands, no changes to the Compose file were needed, and the file’s obsolete version: "3.8" line was removed to silence the deprecation warning.

Prevention Best Practices

• Standardize on docker compose (v2). Update scripts, Makefiles, and docs to the plugin syntax; v2 is the actively maintained path.
• Install the plugin explicitly on servers: sudo apt-get install docker-compose-plugin (or the equivalent for your distro), so the command exists on every host.
• Add a compatibility shim only if you must keep the old name — the docker-compose-v2 compatibility package provides a docker-compose wrapper that forwards to the plugin.
• Pin and verify tooling in CI. Add a docker compose version check as the first pipeline step so a missing plugin fails loudly and early.
• Drop the obsolete version: key from Compose files and lint them; see the Docker stack guides for a maintained baseline.

Quick Command Reference

# Check both forms
docker compose version          # v2 plugin (space)
docker-compose version          # v1 standalone (hyphen)

# Install the v2 plugin (Debian/Ubuntu)
sudo apt-get update && sudo apt-get install docker-compose-plugin

# Confirm the plugin is registered
docker info | grep -iA2 'Plugins'

# Bring a stack up with v2
docker compose -f docker-compose.yml up -d

# Validate the file parses
docker compose config

Conclusion

docker-compose: command not found is a naming problem, not a broken engine. Compose v1 (docker-compose, the Python binary) has been superseded by Compose v2 (docker compose, the Docker CLI plugin), and modern installs ship only the latter. Confirm which form exists with docker compose version, install docker-compose-plugin if it is missing, and migrate your scripts to the space-separated syntax. Do that once and this error disappears for good.