Docker Compose Command Not Found Fix

You’re trying to run docker compose up (or maybe docker-compose up) and your terminal answers with something like:

docker: 'compose' is not a docker command.
command not found: docker-compose

This can be confusing because the fix depends on which Compose you’re trying to use, your OS, and how Docker was installed. The good news: it’s usually a quick, mechanical fix once you identify the cause.

Quick check: which Compose command are you using?

Docker Compose comes in two common forms, and the commands are different:

• Compose v2 (plugin): docker compose (space, no hyphen)
• Compose v1 (legacy binary): docker-compose (hyphenated)

First, run these to see what your system recognizes:

docker --version
docker compose version
docker-compose --version

If docker compose version works, you already have Compose v2 and you should prefer it going forward.

If docker compose is not found: install or enable the Compose v2 plugin

When you see “'compose' is not a docker command”, Docker is installed, but the Compose plugin is missing (or Docker is too old).

macOS and Windows (Docker Desktop)

On macOS/Windows, the simplest fix is usually:

• Update Docker Desktop to the latest stable version
• Restart Docker Desktop after updating

Docker Desktop typically bundles Compose v2. If it’s missing, an update usually restores it.

Linux (Docker Engine)

On Linux, Docker Engine can be installed without the Compose plugin. If your distro packages support it, install the plugin package:

# Debian/Ubuntu-style naming (common)
sudo apt-get update
sudo apt-get install docker-compose-plugin

After installation, verify:

docker compose version

If your distro doesn’t provide docker-compose-plugin or it’s outdated, you may have installed Docker from a different source. In that case, reinstall Docker using Docker’s official repository for your distro, then install the plugin from the same source to avoid version mismatches.

If docker-compose is not found: switch to Compose v2 or install the legacy binary

If your terminal says command not found: docker-compose, you have two options:

Option A: Prefer the modern command (recommended)

Use Compose v2 and replace the hyphenated command:

• docker-compose up → docker compose up
• docker-compose down → docker compose down
• docker-compose ps → docker compose ps

If you’re following older tutorials, this single change fixes most “compose not found” issues.

Option B: Keep legacy scripts working (compatibility)

If you have CI scripts or Makefiles that still call docker-compose, you can add a simple shim that forwards to v2:

sudo ln -s "$(command -v docker)" /usr/local/bin/docker-compose

Note: This works only if docker compose already works, because it relies on the Docker CLI having the Compose plugin.

Another common approach is a shell alias:

alias docker-compose='docker compose'

Aliases won’t help in non-interactive environments (like many CI runners), but they’re fine for local development.

If it’s installed but still not found: PATH and permissions issues

Sometimes Compose is installed, but your shell can’t find it. This usually shows up when:

• You installed Docker/Compose using a different method than your system package manager
• Your terminal session hasn’t picked up updated PATH settings
• The binary exists but doesn’t have execute permission

Try these checks:

which docker
which docker-compose
docker info

If which docker-compose prints nothing, but you’re sure it’s installed, locate it:

sudo find / -name docker-compose 2>/dev/null | head

If you find it in a directory that isn’t on your PATH, add that directory to your PATH (in .zshrc or .bashrc) and restart the terminal.

A common gotcha: mixing Snap, apt, and Docker Desktop installs

On Linux, “Compose not found” can happen when Docker is installed from one source and Compose from another (or not at all). For example:

• Docker installed via Snap, but you try to install Compose via apt
• Docker installed from the distro repo, but you follow instructions meant for Docker’s official repo

When versions don’t align, Docker may run but plugins won’t load correctly.

A stable fix is to pick one installation source and stick to it for Docker + Compose. If you’re using Docker’s official repo, install both Docker Engine and the Compose plugin from there.

A reliable “works in most cases” fix path

If you just want the shortest path to green and you don’t need legacy compatibility:

1. Make sure Docker itself runs: docker --version
2. Install/enable Compose v2 (Desktop update on macOS/Windows, plugin install on Linux)
3. Use docker compose going forward
4. Verify with docker compose version

Once Compose v2 is working, most “docker compose command not found” errors disappear for good—especially if you standardize on the space-based command in docs and scripts.