Fix: Unable to Locate Package docker-compose-plugin (Ubuntu/Debian 2026)
E: Unable to locate package docker-compose-plugin means apt cannot find the package, because the default Ubuntu and Debian repositories do not ship it — only Docker's own APT repository does. Add Docker's official repo, run sudo apt-get update, then sudo apt-get install docker-compose-plugin. The five copy-paste commands are below, followed by the three error variants people hit next.
E: Unable to locate package docker-compose-plugin
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/ubuntuexactly as shown. - Debian 11 (Bullseye), 12 (Bookworm) — swap
ubuntufordebianin 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_CODENAMEreports the Mint codename, which Docker's repo does not know. Override it manually, e.g. set$(. /etc/os-release && echo "$UBUNTU_CODENAME")instead, or hardcodejammy/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
Frequently asked questions
What does 'E: Unable to locate package docker-compose-plugin' mean?
It means apt searched every configured repository and found no package by that name. The default Ubuntu and Debian repositories do not carry docker-compose-plugin — only Docker's official APT repository does. Adding that repository and running 'sudo apt-get update' fixes it.
How do I fix 'Unable to locate package docker-compose-plugin' on Ubuntu 24.04?
Install the prerequisites, add Docker's GPG key to /etc/apt/keyrings/docker.gpg, add the Docker repository line for your codename (noble on 24.04), run 'sudo apt-get update', then 'sudo apt-get install docker-compose-plugin'. The same five steps work on Ubuntu 20.04 and 22.04.
Why does apt say 'Package docker-compose-plugin has no installation candidate'?
The repository is configured but the codename in /etc/apt/sources.list.d/docker.list does not match your release, so no version applies to your system. Run '. /etc/os-release && echo $VERSION_CODENAME', correct the codename in that file, then 'sudo apt-get update' and retry.
Is docker-compose-plugin the same as docker-compose?
No. docker-compose with a hyphen is the old standalone Python binary, deprecated since 2023. docker-compose-plugin adds the modern 'docker compose' subcommand (with a space) to the Docker CLI. Installing both causes a dpkg overwrite error, so pick the plugin.
Why can't apt find docker-compose-v2?
Because docker-compose-v2 was never an official Docker package name, despite appearing in older guides. Install docker-compose-plugin instead — that is the package that provides Compose v2.
Does this work on Raspberry Pi and other arm64 machines?
Yes. The 'arch=$(dpkg --print-architecture)' part of the repository line resolves to arm64 or armhf automatically, so the same commands work without changes.
Can I install docker-compose-plugin without sudo?
No. apt needs root to add a repository and install system packages. If you have no root on the machine, use a rootless Docker setup or a hosted environment that ships Compose already.
Still stuck?
If you just want to get your app running without fighting Linux package managers, try Hostim.
Hostim.dev gives you a pre-configured Docker environment. Just bring your code or Compose file.