Skip to main content

Fix: Unable to Locate Package docker-compose-plugin (Ubuntu/Debian 2026)

If you are trying to install Docker Compose on Ubuntu or Debian and see this error:

E: Unable to locate package docker-compose-plugin

It means your package manager (apt) cannot find the docker-compose-plugin package in your configured repositories. This usually happens because you are using the default OS repositories instead of the official Docker repository.

TL;DR​

The default Ubuntu and Debian repos do not ship docker-compose-plugin. You need to add Docker's official APT repo, then apt install docker-compose-plugin. Full steps below, works on Ubuntu 20.04, 22.04, 24.04, and Debian 11/12.

The Fix​

To fix this, you need to set up the official Docker repository.

1. Update apt and install prerequisites​

sudo apt-get update
sudo apt-get install ca-certificates curl gnupg

2. Add Docker's GPG key​

sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

3. Add the repository​

echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

4. Update and Install​

Now that the repository is added, update the package index and install the plugin:

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

5. Verify​

Check if it works:

docker compose version

Ubuntu 22.04 vs 24.04 vs Debian 11/12​

The 5 steps above work on all of them, but with one gotcha:

  • Ubuntu 22.04 (Jammy), 24.04 (Noble) — use the URL https://download.docker.com/linux/ubuntu exactly as shown.
  • Debian 11 (Bullseye), 12 (Bookworm) — swap ubuntu for debian in both the GPG key URL and the repo line: https://download.docker.com/linux/debian.
  • Linux Mint, Pop!_OS, Zorin — these are Ubuntu-based but VERSION_CODENAME reports the Mint codename, which Docker's repo does not know. Override it manually, e.g. set $(. /etc/os-release && echo "$UBUNTU_CODENAME") instead, or hardcode jammy / noble.

Variant: "Package 'docker-compose-plugin' has no installation candidate"​

Same root cause as Unable to locate. The package exists in apt's index but no version matches your release. Almost always means you added the repo line for the wrong distro codename. Run:

. /etc/os-release && echo "$VERSION_CODENAME"

and confirm the codename matches the one in /etc/apt/sources.list.d/docker.list. Fix the codename, run sudo apt-get update, retry the install.

Variant: dpkg error "trying to overwrite '/usr/libexec/docker/cli-plugins/docker-compose'"​

Different error, same family. You have the old docker-compose standalone binary installed, and it conflicts with the plugin. Remove the old one first:

sudo apt-get remove docker-compose
sudo rm -f /usr/local/bin/docker-compose /usr/libexec/docker/cli-plugins/docker-compose
sudo apt-get install --reinstall docker-compose-plugin

After this, only docker compose (with a space) will work. The legacy docker-compose (with a hyphen) is gone, which is what you want — it has been deprecated since 2023.

Variant: docker-compose-v2 not found​

Some old guides reference docker-compose-v2. That package name was never official. Always install docker-compose-plugin instead.

Why did this happen?​

The docker-compose-plugin package is specific to Docker's modern installation method (Docker Desktop or Docker Engine via their repo). Older guides might suggest installing docker-compose (the standalone python binary), but the modern standard is the plugin which adds the compose subcommand to the docker CLI.

FAQ​

Why does apt install docker-compose-plugin fail on a fresh Ubuntu 24.04? Default Ubuntu repos do not ship the plugin. Add Docker's official APT repo (steps above) and try again.

Is docker-compose-plugin the same as docker-compose? No. docker-compose (hyphen) is the old standalone Python binary, deprecated. docker-compose-plugin adds the modern docker compose (space) subcommand to the Docker CLI.

Can I install both? Avoid it. They share the same binary path and you will hit the dpkg overwrite error above.

Does this work on Raspberry Pi (arm64/armv7)? Yes. The arch=$(dpkg --print-architecture) part of the repo line picks the right architecture automatically.

What about installing without sudo? Not possible for apt. You need root to add the repo and install packages.

Still stuck?​

If you just want to get your app running without fighting Linux package managers, try Hostim.

Deploy on Hostim

Hostim.dev gives you a pre-configured Docker environment. Just bring your code or Compose file.