Docker-Compose: Command Not Found | Fix In 5 Steps

You run docker-compose up, ready to bring your stack online, and your terminal hits you with command not found. Annoying? Yep. Hard to fix? Almost never.

This error has a short list of real causes. Either Compose isn’t installed, it’s installed under the newer command name, or your shell can’t see it through PATH.

Below you’ll get a tight triage flow, then clean fixes for Linux, macOS, and Windows. You’ll also see how to keep older scripts working without changing every repo you touch.

What This Error Is Telling You

Your shell resolves a command by scanning folders listed in PATH. If no matching executable is found, you get “not found.” That’s all this message means at the system level.

With Docker Compose, there’s an extra twist. Many modern installs ship Compose as a Docker CLI plugin, so the command becomes docker compose (a space), not docker-compose (a hyphen). If you type the hyphen form on a machine that only has the plugin, you can see docker-compose: command not found even though Compose is installed.

Symptom	Fast Check	Most Likely Fix
docker-compose: command not found	Run docker compose version	Use docker compose or add a hyphen alias
docker: 'compose' is not a docker command	Run docker version	Install the Compose plugin
Works in one terminal, fails in another	Compare shell startup files	Reload the shell or fix PATH

Do this quick triage before you install anything. It keeps you from fixing the wrong problem.

• Check Docker First — Run docker version. If Docker itself fails, fix Docker before you touch Compose.
• Check The Space Command — Run docker compose version. A version string means Compose V2 is already present.
• Check The Hyphen Command — Run docker-compose version. If it prints, you already have the legacy binary.
• Retry In A Fresh Shell — Close the terminal, open a new one, then try again. Old sessions can keep stale PATH.

Docker-Compose: Command Not Found On Linux With Fast Fixes

Linux is where this pops up most because installs vary. Some people install Docker from distro repos, some use Docker’s repo, some copy binaries by hand, and some work inside WSL.

Your goal is simple: get Compose installed in a way your system can see, then pick one command name you’ll use going forward.

Install The Compose Plugin With Your Package Manager

If you installed Docker Engine from Docker’s own repository, your package manager often has a matching Compose plugin package. These are the common commands.

• Ubuntu Or Debian — Run sudo apt-get update, then sudo apt-get install docker-compose-plugin.
• Fedora — Run sudo dnf install docker-compose-plugin.
• RHEL Or CentOS — Run sudo yum install docker-compose-plugin on systems that still use yum.

Then verify in the same terminal session.

docker compose version
docker compose ls

Manual Plugin Install When Packages Don’t Fit

Some machines won’t have the package you need, or you may be on a minimal server where you prefer a manual install. In that case, Compose V2 can be installed as a CLI plugin file in Docker’s plugin directory layout.

• Pick The Target Folder — Use ~/.docker/cli-plugins for a single user, or /usr/local/lib/docker/cli-plugins for all users.
• Mark It Executable — Run chmod +x on the plugin file, or the Docker CLI can’t run it.
• Verify With The Docker CLI — Run docker compose version after reopening your shell.

When you do a manual install, the most common miss is putting the file in the wrong directory name. The folder must be cli-plugins, not a look-alike path.

Fix Permission And Group Issues That Masquerade As “Not Found”

On some systems, you can run Docker as root, but your normal user can’t talk to the Docker daemon. That can lead to confusing output while you’re testing Compose.

• Test With A Simple Docker Call — Run docker ps. If it errors with a permission message, fix daemon access first.
• Add Your User To The Docker Group — On many distros you can run sudo usermod -aG docker $USER, then log out and back in.
• Recheck After Login — Run docker version again in a new session to confirm the change took effect.

This isn’t the same as docker-compose: command not found, but people often hit both during setup and lump them together. Separate the problems and you’ll move faster.

Use docker compose And Keep Moving

If docker compose version works, you already have Compose V2. At that point, the fastest fix is switching to the space command and continuing your work.

Most of the time, you can take any tutorial that uses the hyphen form and run the same subcommands with the space form. You’re not rewriting your stack, you’re just calling it differently.

Common Command Swaps That Cover Daily Use

• Start Services — Use docker compose up -d to start everything in the background.
• Stop And Remove — Use docker compose down to stop containers and remove the Compose network.
• Follow Logs — Use docker compose logs -f to tail logs while you debug.
• See What’s Running — Use docker compose ps to check service status.
• Validate The YAML — Use docker compose config to render a final config and catch typos early.

If your repo includes scripts, pick one form and standardize. A mixed repo where some docs say one thing and scripts run another is a steady source of avoidable mistakes.

Keep Older Repos Working With A Hyphen Alias

Sometimes you can’t change the command name. A Makefile might call docker-compose, a CI job might be pinned, or you might be running a script you don’t want to edit. In those cases, add a bridge from the hyphen name to the space command.

Add A Shell Alias For Interactive Use

An alias is quick and safe for your own terminal sessions. Put it in your shell profile, then reload.

• Bash Alias — Add alias docker-compose='docker compose' to ~/.bashrc.
• Zsh Alias — Add the same line to ~/.zshrc.
• Reload The Profile — Run source ~/.bashrc or open a new terminal window.

Add A Wrapper Script For System-Wide Use

If you need the hyphen name inside non-interactive jobs, a wrapper file on PATH is steadier than an alias. This writes a tiny script to /usr/local/bin.

sudo sh -c 'printf "%s\n" "#!/bin/sh" "exec docker compose \"\$@\"" > /usr/local/bin/docker-compose'
sudo chmod +x /usr/local/bin/docker-compose

Now docker-compose should run the plugin under the hood, and old scripts can keep working without edits.

When Compose Exists But Your Shell Still Can’t Find It

This is the sneaky case: you installed something, you’re sure you did, but the command still fails. Treat it like command resolution, not a Docker feature problem.

Check What Your Shell Sees

These commands tell you whether your shell can resolve the name you’re typing.

• Locate The Hyphen Name — Run command -v docker-compose to see the resolved path, if any.
• Locate The Space Name — Run docker compose version to verify the plugin is callable from this shell.
• Clear Cached Lookups — In Bash, run hash -r and retry the command.

Fix PATH When You Installed To A Custom Folder

If you placed a wrapper or binary in a directory that isn’t on PATH, the file can exist and still act “missing.” Print PATH and compare it to where you installed.

echo "$PATH"

If the folder you used is not in that output, add it to your shell profile file and reopen the terminal.

Avoid Mixed Installs That Confuse Teams

You can have both the old standalone docker-compose and the new plugin on one machine. That can be fine, but it can also create “works on my laptop” moments when scripts call one name and teammates call another.

• Pick A Default — Use docker compose as the default in docs and scripts.
• Remove Stray Copies — If you copied an old binary into /usr/local/bin, remove it when you no longer need it.
• Verify Both Names — Run docker compose version and docker-compose version to confirm what each name runs.

macOS And Windows Checks That Save Time

On macOS and Windows, Docker Desktop bundles Compose V2. If you hit this error there, it’s often a stale terminal session or a mismatch between where you’re running commands and where Docker is installed.

macOS Checks

• Confirm Desktop Is Running — Open Docker Desktop, wait until it shows it’s running, then retry in a new terminal window.
• Test The Plugin — Run docker compose version and confirm it prints a version string.
• Compare Shell Config — If one terminal works and another fails, compare shell startup files and PATH.

Windows Checks

• Restart Terminals — Close every PowerShell or Windows Terminal window after install, then open a new one.
• Confirm Docker Desktop CLI — Run docker version. If the client prints and the server is reachable, the CLI is wired up.
• Decide On WSL Use — If you work inside WSL, either install Docker Engine plus the Compose plugin in that distro, or enable Docker Desktop’s WSL integration and stick to that setup.

After you fix it, run a short sanity set so you know the whole chain works.

docker version
docker compose version
docker compose config

Prevent This From Showing Up Again

Once you’ve solved it once, a small guard keeps it from stealing time later.

• Standardize The Command — Use docker compose across docs and scripts, then add a hyphen alias only when you truly need it.
• Add A Preflight Check — At the top of scripts, run docker compose version and exit with a clear message if it fails.
• Keep One Install Path — Mixing copied binaries, old distro packages, and manual plugin files makes troubleshooting slower.
• Capture Two Outputs — Save docker version and docker compose version in your notes when something breaks.

If you’re still seeing docker-compose: command not found after everything above, you’re almost always in one of two situations: you installed Compose in a different user context than the shell you’re using, or you’re inside a different Linux instance than you think.

In plain terms, the fix is to verify in the same place you run your commands. Check docker version, then check docker compose version. Once those two work in that shell, the error stops being a mystery and becomes a naming choice.