Fix 'docker-compose: command not found' and migrate to Compose v2

Why you see this error

If you run docker-compose and get command not found, you likely:

• Don’t have legacy Compose v1 installed, or it was removed.
• Are on a system where Compose v2 is installed as a Docker CLI plugin and should be invoked as docker compose (space, not hyphen).

Compose v2 is the supported path. It is integrated into the Docker CLI as a plugin and is faster, more reliable, and maintained. The fix is either to use docker compose directly or install the v2 plugin and migrate your scripts.

Quickstart (TL;DR)

• macOS and Windows (Docker Desktop):

  • Use: docker compose up -d
  • Verify: docker compose version
  • If not found, update Docker Desktop.

• Linux (Docker Engine):

  • Debian/Ubuntu: sudo apt-get update && sudo apt-get install -y docker-compose-plugin
  • Fedora/RHEL/CentOS: sudo dnf install -y docker-compose-plugin or sudo yum install -y docker-compose-plugin
  • Arch-based: sudo pacman -S docker-compose-plugin
  • Verify: docker compose version

• Optional shim to keep old scripts working:

  • Bash/Zsh: add to your shell profile:

docker-compose() { docker compose "$@"; }

Minimal working example

compose.yaml:

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

Run it with Compose v2:

# Start in detached mode
docker compose up -d

# Test locally
curl -I http://localhost:8080/

# Stop and clean up
docker compose down

Step-by-step fix and migration

1. Confirm Docker and Compose state

# Docker Engine
docker version

# Compose v2 (preferred)
docker compose version || true

# Legacy v1 (if present)
docker-compose version || true

• If docker compose prints a version, you’re ready. Use it instead of docker-compose.
• If neither exists, install the Compose v2 plugin.

1. Install Compose v2 as a CLI plugin

• Debian/Ubuntu:

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

• Fedora/RHEL/CentOS:

sudo dnf install -y docker-compose-plugin || sudo yum install -y docker-compose-plugin

• Arch-based:

sudo pacman -S docker-compose-plugin

• Verify after install:

docker compose version

Notes:

• CLI plugins are typically discovered under one of:
  • /usr/lib/docker/cli-plugins/
  • /usr/libexec/docker/cli-plugins/
  • /usr/local/lib/docker/cli-plugins/
  • $HOME/.docker/cli-plugins/
• The plugin file is named docker-compose and must be executable.

1. Replace commands in scripts and docs

• Use docker compose instead of docker-compose everywhere.
• Update CI pipelines to install docker-compose-plugin on Linux runners.

1. Optional: keep docker-compose working

• Bash/Zsh shim:

# ~/.bashrc or ~/.zshrc
docker-compose() { docker compose "$@"; }

• PowerShell shim:

# $PROFILE
function docker-compose { docker compose $args }

This avoids touching system paths and cleanly forwards to v2.

1. Migrate your Compose files

• Compose v2 supports docker-compose.yml, docker-compose.yaml, and compose.yaml (preferred).
• The version: field is no longer required; you can remove it in most cases.
• Behavior is largely compatible; validate with:

docker compose config

Command mapping (v1 → v2)

Platform-specific notes

• macOS: Docker Desktop ships Compose v2; no separate install needed. Use docker compose. If it’s missing, update Desktop.
• Windows: Docker Desktop ships Compose v2. Use docker compose in PowerShell or CMD. If docker-compose is missing, prefer a shim function rather than relying on old shims.
• WSL2: If using Docker Desktop’s engine, docker compose works inside WSL. If running a native Docker Engine inside the distro, install docker-compose-plugin in that distro.

Common pitfalls

• Old Python v1 on PATH: If you previously installed docker-compose via pip, it may mask behavior. Remove it to avoid conflicts:

pip uninstall docker-compose || pip3 uninstall docker-compose
hash -r

• Wrong plugin location or permissions: Ensure the plugin is named docker-compose, is executable, and sits under a recognized cli-plugins directory.

• “Cannot connect to the Docker daemon”: This is not a Compose issue. Make sure Docker Engine is running and your user has permission (e.g., is in the docker group on Linux), or prefix with sudo.

• CI images missing the plugin: Add an install step for docker-compose-plugin or switch the runner image to one that includes it.

Performance notes with Compose v2

• Faster startup: v2 is Go-based and initializes quicker than Python v1.
• Parallel operations: docker compose pull --parallel and parallelized builds speed up pipelines.
• BuildKit integration: Enable faster, cache-friendly builds with BuildKit (set DOCKER_BUILDKIT=1 for docker build and builds triggered from Compose).
• Logs and progress: For low-overhead output in CI, use --progress=plain (for builds) and --ansi never (for logs).

Tiny FAQ

• Is docker-compose deprecated?

  • Yes. Compose v1 is end-of-life. Use docker compose (v2).

• Can I keep using docker-compose in scripts?

  • Prefer updating to docker compose. If that’s hard, add a local shim function that forwards to v2.

• How do I check which Compose I’m using?

  • Run docker compose version. If you only see docker-compose version, you’re on v1.

• Do I need to rewrite my YAML?

  • Usually no. Remove the version: key if present and validate with docker compose config.

• Where does the plugin live?

  • One of: /usr/lib/docker/cli-plugins, /usr/libexec/docker/cli-plugins, /usr/local/lib/docker/cli-plugins, or ~/.docker/cli-plugins.