Docker Compose: Command Not Found, Fixed

You ran docker-compose up -d on a box where that exact command has worked a dozen times before - or a Pi you just flashed, or a Synology you just rebooted - and the shell answers docker-compose: command not found. Docker itself is clearly installed; docker ps works fine. So what broke?

Why This Happens: You're Missing V2, Not Docker Compose Itself

Compose V1 - the standalone docker-compose Python binary - stopped receiving updates in July 2023 and was dropped from new Docker Desktop releases. It was replaced by Compose V2, a Docker CLI plugin invoked as docker compose - a space where there used to be a hyphen. Docker's own migration guide confirms V2 is a drop-in replacement for V1's functionality, syntax changes aside.

If you installed Docker any time in the last couple of years through an official channel - Docker Engine's apt repo, Docker Desktop, or a current distro package - you almost certainly have V2 and only V2. The docker-compose binary was never there to begin with. The error isn't "Compose is missing"; it's "the specific command you typed is missing."

The 30-Second Check

Before changing anything, find out which situation you're actually in:

docker compose version     # V2 - the plugin, no hyphen
docker-compose --version   # V1 - the old standalone binary

If the first command prints a version, you have Compose and this is purely a syntax issue - every command in every script, alias, and muscle-memory habit needs the hyphen replaced with a space. If both commands fail, skip ahead to Still Not Found After Installing? - that's a real missing-install or PATH problem, not the V1/V2 split.

Fixing It on Debian and Ubuntu

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

Fixing It on Raspberry Pi OS

I moved a handful of services off an aging Raspberry Pi onto a Debian box last year, and the old install instructions I'd bookmarked - pip3 install docker-compose - installed V1, the exact binary that's now deprecated. Raspberry Pi OS's ARM architecture isn't served by Debian/Ubuntu's docker-compose-plugin apt package either, so the clean path on a Pi is Docker's own convenience script, which detects the ARM architecture and installs the current V2 plugin directly:

curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
docker compose version

Skip any guide that still tells you to pip3 install docker-compose on a Pi in 2026 - that path installs an unmaintained V1 build with no further security updates.

Fixing It on Synology (Container Manager)

This is the case most troubleshooting guides skip entirely, because Synology doesn't work like a regular Linux install. DSM 7.2 renamed the Docker package to Container Manager, and Compose runs through its Project tab in the DSM web interface, or over SSH as docker compose - there's no separate docker-compose binary to apt install because Synology doesn't expose apt in the first place.

To run Compose from the command line on a Synology NAS:

1. Enable SSH in Control Panel → Terminal & SNMP.
2. SSH in: ssh <your-username>@<nas-ip>.
3. Run Compose with sudo docker compose -f /path/to/compose.yaml up -d - note the space, and that DSM expects compose.yaml, not the older docker-compose.yml name, in some DSM versions' Project tab.

Still Not Found After Installing? Check Your PATH

Rarer, but real: the plugin or binary is actually on disk, but your shell's PATH doesn't include the directory it lives in. Find it first:

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

If that returns a path like /usr/local/bin/docker-compose, either add that directory to your PATH (append export PATH="$PATH:/usr/local/bin" to ~/.bashrc or ~/.zshrc), or symlink it into a directory already on your PATH:

sudo ln -s /usr/local/bin/docker-compose /usr/bin/docker-compose

Keeping Old docker-compose Scripts Working

If you have CI jobs, deploy scripts, or muscle memory that still call docker-compose with the hyphen and rewriting every reference today isn't realistic, a one-line shell function bridges the gap without reinstalling anything:

echo 'docker-compose() { docker compose "$@"; }' >> ~/.bashrc
source ~/.bashrc

FAQ

Why does docker-compose say command not found if Docker is already installed?

Because current Docker installs ship Compose V2, a plugin invoked as docker compose (space), not the old standalone docker-compose (hyphen) binary from Compose V1. Docker itself works fine; the specific hyphenated command was simply never installed.

How do I know if I have Compose V1 or V2?

Run docker compose version (V2, no hyphen) and docker-compose --version (V1, with a hyphen). Whichever one succeeds tells you which you have; it's possible to have both, V2 only, or neither.

Can I still use the docker-compose command after installing V2?

Not natively - V2 only responds to docker compose. You can restore the old syntax with a shell alias or function that forwards to docker compose, which is useful for old scripts but doesn't change what's actually installed.

Does Raspberry Pi OS support Docker Compose?

Yes, but install it via Docker's official convenience script (get.docker.com), which detects the Pi's ARM architecture and installs current Compose V2 - not the old pip3 install docker-compose route, which installs an unmaintained V1 build.

Why can't I find docker-compose on my Synology NAS?

Because it isn't there to find. DSM 7.2 renamed the Docker package to Container Manager, which runs Compose V2 through its Project tab or over SSH as docker compose - there's no standalone binary to install, and manual V1 installs found in older forum posts should be avoided.

The Bottom Line

Almost every docker-compose: command not found error traces back to that one date - you're on a system that only ever had V2, and the hyphenated command simply doesn't exist there. Confirm it with docker compose version before installing anything new, then follow the path for your actual OS above. If this came up while you were still laying out your first stack rather than fixing an existing one, our homelab beginner's guide and Docker Compose self-hosting guide start a step earlier.