sudo docker-compose says command not found on a Linux server
docker-compose: command not foundShort answer
Current Docker installs ship Compose as a CLI plugin, so the command is docker compose with a space, and no docker-compose file exists. Install docker-compose-plugin, or make sure a manually downloaded binary sits in a cli-plugins folder and is executable. If the file exists but only sudo fails, sudo is using its own secure PATH.
Fix it fast
1Find out which cause you have
Find out whether Compose exists as a plugin, as a separate file, or not at all. The three answers point to the three causes below.
docker compose version command -v docker-compose sudo sh -c 'command -v docker-compose'2Match what you see, then jump to its fix
- 1
docker compose version prints a version, while docker-compose is not found anywhereCompose is installed as a Docker plugin, so the hyphenated command does not existFix - 2
You downloaded docker-compose-linux-x86_64 by hand and docker compose still says it is not a docker commandA manually downloaded Compose binary is in the wrong folder or not executableFix - 3
command -v docker-compose prints a path as your user, but sudo says command not foundsudo replaces your PATH, so a docker-compose file that works for you is not foundFix
- 1
What does the error look like?
docker-compose: command not foundsudo: docker-compose: command not found
Cause 1 of 3
Compose is installed as a Docker plugin, so the hyphenated command does not exist
1Check
Docker documents Compose as a plugin of the docker CLI and verifies it with docker compose version. A plugin install never creates a docker-compose executable.
docker compose version2Fix
Run your commands with a space instead of a hyphen. If the plugin is missing, install it from Docker's package repository.
# Ubuntu / Debian
sudo apt-get update
sudo apt-get install docker-compose-plugin
# RHEL family, Fedora, Rocky, Alma
sudo yum install docker-compose-plugin
# then
docker compose up -d3Verify
The version command prints a version number.
docker compose versionConfirmed by docs.docker.com
Cause 2 of 3
A manually downloaded Compose binary is in the wrong folder or not executable
1Check
Docker's manual install puts the file at ~/.docker/cli-plugins/docker-compose for one user, or /usr/local/lib/docker/cli-plugins/docker-compose for all users, and it must be executable. A plugin saved in your home folder is not seen by root when you use sudo.
ls -l ~/.docker/cli-plugins/docker-compose
ls -l /usr/local/lib/docker/cli-plugins/docker-compose2Fix
Move the file to the all-users folder and set the executable bit. Download the file for your architecture and version from the link on Docker's page.
sudo mkdir -p /usr/local/lib/docker/cli-plugins
sudo mv ~/.docker/cli-plugins/docker-compose /usr/local/lib/docker/cli-plugins/docker-compose
sudo chmod +x /usr/local/lib/docker/cli-plugins/docker-compose3Verify
Both a normal user and sudo can run it.
docker compose version
sudo docker compose versionConfirmed by docs.docker.com
Cause 3 of 3
sudo replaces your PATH, so a docker-compose file that works for you is not found
1Check
When the secure_path option is set in sudoers, sudo uses that value instead of your own PATH. A file in a folder outside it, such as a home directory, is invisible to sudo.
sudo sh -c 'echo $PATH'
echo $PATH2Fix
Call the file by its full path, or move to docker compose, which sudo finds through the docker command. Better still, add your user to the docker group so you do not need sudo for Docker commands.
sudo "$(command -v docker-compose)" up -d
# or
sudo docker compose up -d3Verify
The command starts without the not found message.
sudo docker compose psConfirmed by sudo.ws
How do I stop it coming back?
- Write docker compose (with a space) in scripts, README files and CI jobs.
- Install Compose from Docker's package repository so it updates with apt or yum.
- After a manual download, always run docker compose version as both your user and sudo.
Sources
How was this page made?
I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.
Which stack is behind this page?
Projects of mine built on the same technologies:
Related fixes
Servers
Apache logs SIGWINCH and exits on its own
the httpd container stops although nothing crashed
SIGWINCH is Apache's graceful-stop signal.
2 causes, each with a fixServers
sam local fails: Running AWS SAM projects locally requires Docker
Cannot connect to the Docker daemon. Is the docker daemon running on this host?
sam local start-api and sam local invoke run your function inside a Docker container, so SAM stops if it cannot talk to Docker.
3 causes, each with a fixServers
dnf fails to download repo metadata in a CentOS 8 Docker build
The same Dockerfile built fine before 2022
CentOS Linux 8 reached end of life on 31 December 2021 and its content left the mirrors.
2 causes, each with a fixServers
pip install confluent-kafka fails because librdkafka/rdkafka.h is missing
pip stops while building confluent-kafka from source
The error means pip is compiling confluent-kafka from source, and the compiler cannot find the librdkafka C headers.
3 causes, each with a fixServers
Cypress says the npm package is installed but the binary is missing
Cypress binary is missing after npm install in CI or in a Docker build
The npm package is only a launcher.
3 causes, each with a fixServers
A dev container port does not open in the browser when Docker runs on a remote host
If your application only accepts calls from localhost, it will reject connections from published ports
Three things usually break it: the app listens only on localhost inside the container, so published ports are rejected; you open the container port instead of the mapped localhost port VS Code shows; or you changed appPort or a Compose ports list and did not rebuild.
3 causes, each with a fix