Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Servers, nginx and Docker

sudo docker-compose says command not found on a Linux server

Errordocker-compose: command not found

Short 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.

  • Applies to Docker Compose plugin, Docker Engine, Ubuntu 24.04, Amazon Linux 2023
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 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'
  2. 2Match what you see, then jump to its fix

    1. 1docker 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. 2You 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. 3command -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

What does the error look like?

  • docker-compose: command not found
  • sudo: 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 version

2Fix

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 -d

3Verify

The version command prints a version number.

docker compose version

Confirmed by docs.docker.com

Did this fix it?

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-compose

2Fix

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-compose

3Verify

Both a normal user and sudo can run it.

docker compose version
sudo docker compose version

Confirmed by docs.docker.com

Did this fix it?

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 $PATH

2Fix

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 -d

3Verify

The command starts without the not found message.

sudo docker compose ps

Confirmed by sudo.ws

Did this fix it?

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

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

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.