Docker "docker-compose: command not found" (v1 vs v2) in CI
Compose v2 ships as a Docker CLI plugin invoked as docker compose, not the legacy standalone docker-compose binary. Runners without the old binary fail any script that calls docker-compose.
What this error means
A step calling docker-compose ... fails with docker-compose: command not found, while docker compose ... works. Common after a runner image upgrade.
docker
docker-compose: command not found
Error: Process completed with exit code 127.Common causes
Only Compose v2 plugin installed
The runner has the docker compose plugin but not the standalone docker-compose v1 binary.
Scripts hardcode the v1 command
Existing scripts and Makefiles call docker-compose, which no longer exists on the image.
How to fix it
Use the v2 subcommand
- Replace docker-compose with docker compose in scripts and workflows.
Terminal
docker compose up -d
docker compose buildProvide a compatibility shim if needed
- If many scripts use the old name, install the standalone binary or alias it.
Terminal
docker compose version || echo "v2 plugin missing"How to prevent it
- Standardize on the
docker composev2 subcommand across scripts and workflows, and verify availability with docker compose version in setup. This is deterministic, not transient.
Frequently asked questions
What causes ""docker-compose: command not found""?
The runner has the docker compose plugin but not the standalone docker-compose v1 binary.
How do I fix "docker-compose: command not found"?
Use the v2 subcommand
Related guides
Docker Compose "service failed to build" in CIFix the Docker Compose "service ... failed to build" error in CI, where a service image build fails and the r…
Docker Compose "network not found" in CIFix the Docker Compose "network <name> not found" / "network ... declared as external, but could not be found…
Docker Compose "dependency failed to start: container is unhealthy" in CIFix the Docker Compose "dependency failed to start: container ... is unhealthy" error in CI, where a depends_…