Fix 'docker: compose is not a docker command' (CLI plugin)

Overview

The error "docker: 'compose' is not a docker command" means the Docker CLI cannot find the Compose v2 plugin. Docker Compose v2 is invoked as docker compose and is distributed as a CLI plugin. Without it, the docker CLI won’t recognize compose.

Key points:

• Compose v2 = docker compose (preferred, Go-based plugin)
• Compose v1 = docker-compose (legacy, Python-based, deprecated but still usable)
• Fix by installing the Compose v2 CLI plugin or use docker-compose as a temporary fallback

Quickstart (most cases)

1. Check if the plugin exists:
   • docker compose version
2. If it fails, install the plugin:
   • Debian/Ubuntu: sudo apt-get update && sudo apt-get install -y docker-compose-plugin
   • RHEL/CentOS/Fedora: sudo dnf install -y docker-compose-plugin
   • Alpine: sudo apk add docker-cli-compose
   • Arch: sudo pacman -S docker-compose
   • openSUSE: sudo zypper install docker-compose
   • macOS (with Homebrew): brew install docker-compose
   • Windows (with winget): winget install -e --id Docker.DockerDesktop
3. Verify: docker compose version
4. Run a minimal Compose example (see below).

Minimal working example

Create a compose file and bring it up using docker compose.

File: compose.yaml

services:
  web:
    image: nginx:alpine
    ports:
      - "8080:80"

Commands:

# From the directory containing compose.yaml
docker compose up -d

# Verify container is running
docker compose ps

# Tear down when done
docker compose down

If docker compose still fails, use the legacy command temporarily:

# Legacy (v1) fallback if installed
docker-compose up -d

Installation by platform (numbered steps)

1) Debian/Ubuntu

1. Update package lists:

   sudo apt-get update
   

2. Install the Compose v2 plugin:

   sudo apt-get install -y docker-compose-plugin
   

3. Verify:

   docker compose version
   

2) RHEL/CentOS/Fedora

1. Install the plugin:

   sudo dnf install -y docker-compose-plugin
   

2. Verify:

   docker compose version
   

Note: Ensure the Docker repository is enabled on older RHEL/CentOS if the package isn’t found.

3) Alpine

1. Install the plugin package:

   sudo apk add docker-cli-compose
   

2. Verify:

   docker compose version
   

4) Arch Linux

1. Install Compose:

   sudo pacman -S docker-compose
   

2. Verify:

   docker compose version
   

5) openSUSE

1. Install Compose:

   sudo zypper install docker-compose
   

2. Verify:

   docker compose version
   

6) macOS

• Docker Desktop usually includes Compose v2 automatically.
• If you run Docker via Colima or another runtime, install Compose via Homebrew:

  brew install docker-compose
  

• Verify:

  docker compose version
  

7) Windows

• Install or update Docker Desktop (includes Compose v2):

  winget install -e --id Docker.DockerDesktop
  

• On WSL distributions, ensure the Windows Docker CLI is available, or install the package inside the distro (e.g., apt-get install docker-compose-plugin).
• Verify:

  docker compose version
  

Verifying your environment

# Docker Engine and Client
docker version

# Compose plugin
docker compose version

# List compose projects if any
docker compose ls

Expected: docker compose version prints a v2.x.y version. If not, your PATH or plugin installation is incomplete.

Common pitfalls and fixes

• Missing plugin directories

  • The plugin must be discoverable by the Docker CLI. Typical locations:

    Location scope	Directory example
    User	~/.docker/cli-plugins/
    System	/usr/lib/docker/cli-plugins/ or /usr/local/lib/docker/cli-plugins/

  • The plugin binary must be named docker-compose and be executable.

• Mixing v1 and v2

  • docker-compose (v1) may be installed while docker compose (v2) is missing. Either:
    • Install v2 and prefer docker compose, or
    • Continue with docker-compose until you can upgrade.

• Old Docker Engine or CLI

  • Update Docker Engine/CLI if docker is too old to load plugins reliably.

• PATH overshadowing

  • A stale docker-compose in /usr/local/bin may shadow the desired plugin. Remove or update it if needed.

• Corporate proxies / restricted repos

  • Your distro may not see the plugin package. Configure your package manager to use the proper Docker repository or install via a supported distribution method.

• CI images without plugin

  • Minimal base images often omit the plugin. Explicitly install it in your pipeline before running docker compose.

Performance notes

• Compose v2 is a compiled plugin and typically starts faster than v1.
• Use docker compose pull to prefetch images and avoid build-time stalls.
• Parallel pulls/builds are enabled by default in v2; leverage them for faster CI.
• Prefer docker compose up -d for non-interactive environments to minimize TTY overhead.
• Keep compose files small and split by concerns (override and profiles) to speed up iteration.

Tiny FAQ

• Why do I see this error?

  • The Docker CLI cannot find the Compose v2 plugin.

• What is the difference between docker compose and docker-compose?

  • docker compose is v2 (plugin). docker-compose is v1 (legacy). Prefer v2.

• Can I keep using docker-compose?

  • Yes, but it’s deprecated. New features land in v2.

• Do I need Docker Desktop for Compose v2?

  • No. On Linux, install the plugin via your package manager.

• How do I fix this in CI?

  • Add a step to install the plugin (e.g., apt-get install docker-compose-plugin) before running docker compose.

• My plugin installs but docker compose still fails. Why?

  • Check executable name, permissions, and plugin directory. Confirm with docker compose version.