Docker Compose Command Not Found: Fixes for Mac, Linux, and Windows

When you type:

docker-compose up

or:

docker compose up

and your shell replies with something like:

• docker-compose: command not found
• docker: 'compose' is not a docker command
• The term 'docker-compose' is not recognized as the name of a cmdlet...
• Cannot connect to the Docker daemon... (sometimes appears during troubleshooting)

…you’re dealing with one of a few root causes:

1. Docker Compose isn’t installed (or not installed correctly).
2. It is installed, but your PATH doesn’t include the directory where it lives.
3. You’re using the wrong command for your version (docker-compose v1 vs docker compose v2).
4. Docker Desktop / Engine isn’t installed or isn’t running (less common for “command not found”, but often encountered right after you fix it).
5. You’re in a restricted environment (corporate machine, minimal Linux, WSL) where the plugin isn’t available.

This tutorial walks through diagnosis and fixes for macOS, Linux, and Windows, with real commands and deeper explanations so you can understand why each fix works.

1) Understand the Two “Docker Compose” Commands (v1 vs v2)

Before fixing anything, confirm which Compose you’re trying to use:

Compose v1 (legacy)

• Command: docker-compose
• Typically a standalone binary called docker-compose
• Still used in some older docs and systems

Compose v2 (current)

• Command: docker compose (note the space)
• Implemented as a Docker CLI plugin
• Installed alongside Docker Desktop (Mac/Windows) or via packages/plugins on Linux

Many “command not found” errors happen because:

• You installed Docker Compose v2, but you run docker-compose.
• Or you installed v1, but you run docker compose.

Quick check (run these exactly)

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

Interpretation:

• If docker compose version works, you have v2.
• If docker-compose --version works, you have v1.
• If both fail, Compose is missing or not on your PATH.

2) Diagnose the Problem: Is It Missing or Just Not on PATH?

On macOS/Linux (bash/zsh)

Check whether the command exists:

command -v docker
command -v docker-compose

For Compose v2 plugin, also check:

docker compose version

If command -v docker-compose prints nothing, your shell can’t find it. That could mean:

• Not installed, or
• Installed somewhere not in PATH.

To see your PATH:

echo "$PATH"

To locate a binary if it exists somewhere:

which docker-compose
type -a docker-compose

On Windows PowerShell

Check availability:

Get-Command docker
Get-Command docker-compose
docker compose version

If Get-Command docker-compose fails, it’s not found in your PATH (or not installed).

3) Fixes for macOS

3.1 Recommended: Install/Repair Docker Desktop (Compose v2 included)

On macOS, the simplest and most reliable solution is Docker Desktop, which includes Compose v2.

1. Verify Docker Desktop is installed:
   • Look for Docker in Applications
   • Or check from terminal:

ls -l /Applications/Docker.app

2. Start Docker Desktop (required for Docker daemon access):

   • Open Docker Desktop from Applications
   • Wait until it says “Docker Desktop is running”

3. Verify:

docker --version
docker compose version
docker info

If docker compose version works, you’re done (use docker compose up).

If you still need docker-compose (compatibility)

Some scripts expect docker-compose. Docker Desktop often provides a compatibility symlink, but not always.

Check:

docker-compose --version

If it fails but docker compose version works, you can create a wrapper script or symlink.

Option A: Create a wrapper script in /usr/local/bin (Intel)

sudo mkdir -p /usr/local/bin
cat <<'EOF' | sudo tee /usr/local/bin/docker-compose >/dev/null
#!/bin/sh
exec docker compose "$@"
EOF
sudo chmod +x /usr/local/bin/docker-compose

Option B: On Apple Silicon, use /opt/homebrew/bin if Homebrew is installed

sudo mkdir -p /opt/homebrew/bin
cat <<'EOF' | sudo tee /opt/homebrew/bin/docker-compose >/dev/null
#!/bin/sh
exec docker compose "$@"
EOF
sudo chmod +x /opt/homebrew/bin/docker-compose

Then confirm:

docker-compose --version

This doesn’t install Compose v1; it simply forwards docker-compose ... to docker compose ....

3.2 If Docker Is Installed but the CLI Isn’t Found

If you get docker: command not found, Docker Desktop might not have installed its CLI links correctly.

Common checks:

ls -l /usr/local/bin/docker
ls -l /opt/homebrew/bin/docker

Also check if the Docker CLI exists inside the app bundle:

ls -l /Applications/Docker.app/Contents/Resources/bin/docker

If it exists there, you can add it to your PATH (not always recommended long-term, but works):

echo 'export PATH="/Applications/Docker.app/Contents/Resources/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Then:

docker --version
docker compose version

3.3 Homebrew Install (Alternative for CLI tools)

If you want the Docker CLI via Homebrew (useful for CI-like local setups), you can install:

brew update
brew install docker docker-compose

Notes:

• brew install docker-compose may install a separate Compose binary (often v2 or a wrapper depending on brew formulas and your system).
• You still need a Docker daemon somewhere (Docker Desktop, Colima, remote Docker host).

Verify:

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

If Docker daemon isn’t running, you might see daemon connection errors (not “command not found”).

4) Fixes for Linux (Ubuntu/Debian/Fedora/Arch + Generic)

Linux is where “Compose command not found” has the most variety because Compose can be:

• A plugin package (docker-compose-plugin)
• A standalone binary (docker-compose)
• Bundled into Docker Desktop for Linux (less common)

4.1 First: Confirm Docker Engine and CLI

docker --version
docker info

If docker itself is missing, install Docker Engine first (distribution-specific). After Docker works, proceed to Compose.

4.2 Recommended on modern Linux: Install Compose v2 plugin

Ubuntu/Debian (APT)

If you installed Docker from Docker’s official repository, you can install the plugin:

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

Verify:

docker compose version

If that works, you’re done: use docker compose up.

Fedora/RHEL/CentOS (DNF/YUM)

On Fedora:

sudo dnf install -y docker-compose-plugin
docker compose version

On some RHEL-like systems, package names and repos vary. If docker-compose-plugin isn’t found, you may need Docker’s official repo or use the standalone binary method below.

Arch Linux (pacman)

Arch typically provides Compose v2:

sudo pacman -Syu docker docker-compose

Then verify:

docker compose version
docker-compose --version

(Arch may provide both; prefer docker compose if available.)

4.3 If docker compose still fails: Verify plugin discovery paths

Docker Compose v2 is a CLI plugin. Docker looks for plugins in specific directories, commonly:

• System-wide: /usr/lib/docker/cli-plugins/
• Local user: ~/.docker/cli-plugins/

Check if the compose plugin exists:

ls -l /usr/lib/docker/cli-plugins/ 2>/dev/null
ls -l /usr/local/lib/docker/cli-plugins/ 2>/dev/null
ls -l ~/.docker/cli-plugins/ 2>/dev/null

Look for a file named something like:

• docker-compose

Yes, the plugin file is often named docker-compose even though the command is docker compose.

If you find it in ~/.docker/cli-plugins/, ensure it is executable:

chmod +x ~/.docker/cli-plugins/docker-compose
docker compose version

If you find it somewhere unusual, your Docker might not be searching that directory. The simplest fix is to place the plugin in a recognized path (see next section).

4.4 Generic Linux Fix: Install Compose v2 plugin manually (official release binary)

This is useful when:

• Your distro packages are outdated
• The plugin package doesn’t exist
• You’re on a minimal server

Step 1: Create the plugin directory

For your user (no sudo needed):

mkdir -p ~/.docker/cli-plugins

Step 2: Download the Compose plugin binary

Find your architecture:

uname -s
uname -m

Common outputs:

• OS: Linux
• Arch: x86_64 (amd64), aarch64 (arm64)

Download (example uses x86_64; change as needed):

curl -SL "https://github.com/docker/compose/releases/latest/download/docker-compose-linux-x86_64" -o ~/.docker/cli-plugins/docker-compose
chmod +x ~/.docker/cli-plugins/docker-compose

Verify:

docker compose version

If it works, Compose v2 is installed for your user.

If you prefer system-wide install

Use:

sudo mkdir -p /usr/local/lib/docker/cli-plugins
sudo curl -SL "https://github.com/docker/compose/releases/latest/download/docker-compose-linux-x86_64" -o /usr/local/lib/docker/cli-plugins/docker-compose
sudo chmod +x /usr/local/lib/docker/cli-plugins/docker-compose
docker compose version

4.5 Legacy Linux Fix: Install docker-compose v1 (standalone)

Some older environments still use v1. If you truly need docker-compose (v1), you can install via Python pip (not ideal, but sometimes necessary):

python3 --version
pip3 --version
pip3 install --user docker-compose

Then ensure ~/.local/bin is in your PATH:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
docker-compose --version

Caveats:

• Compose v1 is legacy; prefer v2 if possible.
• Pip-based installs can conflict with system Python packaging policies on some distros.

4.6 Common Linux “It’s installed but not found” PATH fixes

If you installed docker-compose somewhere like /usr/local/bin/docker-compose but it’s still “not found”, check:

ls -l /usr/local/bin/docker-compose
echo "$PATH"

If /usr/local/bin isn’t in PATH (unusual but possible in minimal shells), add it:

echo 'export PATH="/usr/local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

For zsh:

echo 'export PATH="/usr/local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

5) Fixes for Windows (Docker Desktop, PowerShell, CMD, WSL)

On Windows, Compose is usually provided by Docker Desktop as Compose v2.

5.1 Confirm Docker Desktop and Compose v2

Open Docker Desktop and ensure it’s running.

Then in PowerShell:

docker --version
docker compose version
docker info

If docker is not found, Docker Desktop may not be installed or its PATH integration failed.

5.2 Fix PATH issues on Windows (Docker CLI not found)

Docker Desktop typically installs Docker CLI into a directory like:

• C:\Program Files\Docker\Docker\resources\bin

Check if docker.exe exists:

Test-Path "C:\Program Files\Docker\Docker\resources\bin\docker.exe"

If it returns True, add that folder to PATH.

Temporary PATH fix (current terminal session only)

$env:Path += ";C:\Program Files\Docker\Docker\resources\bin"
docker --version
docker compose version

Permanent PATH fix (User PATH)

[Environment]::SetEnvironmentVariable(
  "Path",
  [Environment]::GetEnvironmentVariable("Path","User") + ";C:\Program Files\Docker\Docker\resources\bin",
  "User"
)

Close and reopen your terminal, then test again:

docker --version
docker compose version

5.3 docker-compose not recognized but docker compose works

This is very common. Many Windows setups only provide Compose v2 (docker compose).

If you must support docker-compose (for scripts), you can create a small shim.

Option A: Use a PowerShell function (quick, per-profile)

Add to your PowerShell profile:

notepad $PROFILE

Add:

function docker-compose { docker compose @args }

Restart PowerShell, then:

docker-compose version

Option B: Create a docker-compose.cmd shim in a directory on PATH

Pick a directory on your PATH, for example %USERPROFILE%\bin:

mkdir $HOME\bin -Force | Out-Null

Create a shim:

@'
@echo off
docker compose %*
'@ | Set-Content -Encoding ASCII $HOME\bin\docker-compose.cmd

Add $HOME\bin to PATH (User PATH), then reopen terminal:

[Environment]::SetEnvironmentVariable(
  "Path",
  [Environment]::GetEnvironmentVariable("Path","User") + ";$HOME\bin",
  "User"
)

Now:

docker-compose version

5.4 Windows + WSL: Compose missing inside WSL

If you run Ubuntu in WSL and type docker compose, you might get “command not found” because:

• Docker Desktop provides Docker/Compose on Windows
• Your WSL distro may not have the Docker CLI/plugin installed
• Or integration is not enabled

Step 1: Enable Docker Desktop WSL integration

In Docker Desktop:

• Settings → Resources → WSL Integration
• Enable integration for your distro

Step 2: In WSL, check Docker CLI

Inside WSL:

docker --version
docker compose version

If docker is missing in WSL, install the Docker CLI in WSL (not necessarily the daemon):

sudo apt-get update
sudo apt-get install -y docker.io

Then try again. If docker compose is still missing, install the plugin:

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

Note: In WSL with Docker Desktop integration, you typically do not need to run the Docker daemon inside WSL; Docker Desktop runs it.

6) Verify Your Fix with a Real Compose Project

After installation, verify with an actual project rather than only --version.

6.1 Create a minimal Compose file

Create a directory and file:

mkdir -p ~/compose-test
cd ~/compose-test

Create compose.yaml (Compose v2 default name) using a heredoc:

cat > compose.yaml <<'EOF'
services:
  web:
    image: nginx:alpine
    ports:
      - "8080:80"
EOF

6.2 Run it

With Compose v2:

docker compose up -d
docker compose ps

Test in another terminal:

curl -I http://localhost:8080

Stop and clean up:

docker compose down

If you’re using legacy v1:

docker-compose up -d
docker-compose ps
docker-compose down

7) Less Obvious Causes (and How to Spot Them)

7.1 Aliases or shell hashing issues

Sometimes you installed a command, but your shell still “remembers” the old state.

On bash:

hash -r

On zsh:

rehash

Then retry:

docker compose version
docker-compose --version

7.2 Wrong architecture binary

If you downloaded a Linux binary for the wrong architecture, you might see “Exec format error” rather than “command not found”, but it often comes up during manual installs.

Check:

uname -m
file ~/.docker/cli-plugins/docker-compose

7.3 Permissions

If the file exists but isn’t executable:

ls -l ~/.docker/cli-plugins/docker-compose
chmod +x ~/.docker/cli-plugins/docker-compose

7.4 Corporate endpoint protection / blocked execution

On Windows, security tools may block unknown executables. Prefer Docker Desktop’s official installation path and signed binaries. If shims are blocked, use docker compose directly.

7.5 Snap-installed Docker (Ubuntu) and plugin mismatch

If Docker is installed via Snap, plugin paths and packaging can differ. Check:

which docker
docker --version

If it’s from snap, you might consider switching to Docker’s official apt repo for consistent plugin support.

8) Quick “Fix Matrix” (Choose Your Situation)

You typed docker-compose and it says “command not found”

• Try docker compose version
• If it works: use docker compose ... or add a shim/wrapper for docker-compose

You typed docker compose and it says it’s not a docker command

• Install Compose plugin:
  • Ubuntu/Debian: sudo apt-get install -y docker-compose-plugin
  • Fedora: sudo dnf install -y docker-compose-plugin
  • Manual: download plugin to ~/.docker/cli-plugins/docker-compose

docker itself is not found

• Install Docker Desktop (Mac/Windows) or Docker Engine (Linux)
• Fix PATH to include Docker CLI directory

Windows: docker works, docker-compose doesn’t

• Use docker compose
• Or create a PowerShell function / docker-compose.cmd shim

WSL: works in Windows, not in WSL

• Enable Docker Desktop WSL integration
• Install Docker CLI + compose plugin inside WSL if needed

9) Best Practices Going Forward

1. Prefer Compose v2 and the docker compose syntax for new work.
2. If you maintain older scripts, add a compatibility shim rather than forcing v1.
3. Keep your installation method consistent:
   • Docker Desktop on Mac/Windows
   • Docker Engine + docker-compose-plugin on Linux (from a consistent repo)
4. Validate with a real compose.yaml run, not only --version.

10) Final Sanity Checklist (Copy/Paste)

Run the block that matches your OS.

macOS (zsh/bash)

docker --version
docker compose version
docker info
command -v docker-compose || true

Linux

docker --version
docker compose version || true
docker-compose --version || true
ls -l ~/.docker/cli-plugins 2>/dev/null || true

Windows PowerShell

docker --version
docker compose version
Get-Command docker-compose -ErrorAction SilentlyContinue

If docker compose version works, you have a modern, supported Compose installation. If docker-compose still fails, decide whether you truly need it; if yes, add the shim/wrapper described for your platform.

If you share your OS, shell (bash/zsh/PowerShell), and the exact error text, I can pinpoint the shortest fix path (plugin install vs PATH vs command mismatch).