Older guides install Docker Compose on Linux by dropping one binary into /usr/local/bin and calling it as docker-compose. Compose ships as a Docker CLI plugin now, so the binary belongs in a cli-plugins directory and you run it as docker compose. Put it in the wrong directory and Docker cannot see it. Download the wrong architecture and it does more than fail, because it hides a working copy you installed elsewhere.
We cover Docker’s docker-compose-plugin package on Rocky Linux and RHEL, your distro’s own package, and a manual install of the release binary with a sha256 check. The manual route works per user or system-wide, on x86_64 and aarch64, and we also move an old standalone install over without breaking scripts. Every command below was run in November 2026 on Rocky Linux 10, Debian 13 x86_64 and Debian 13 on an arm64 VM, with Docker Compose v5.7.1.
Pick an install route
If Docker Engine came from Docker’s own repository, install Compose from that same repo, because it upgrades with the rest of the engine and you never think about it again. The manual plugin install is for everything else: hosts where you cannot add a repo, a newer Compose than your distro ships, or a user account without root. The table shows where each route puts the binary, which matters later when two copies disagree.
| Route | Binary path | Updates | Use it when |
|---|---|---|---|
Docker repo, docker-compose-plugin | /usr/libexec/docker/cli-plugins/ | With dnf or apt | Docker CE is installed from download.docker.com |
Distro package (Debian docker-compose) | /usr/libexec/docker/cli-plugins/ plus /usr/bin/docker-compose | With apt, lags upstream (2.x line on Debian 13) | You run the distro’s docker.io and older Compose is fine |
| Manual, one user | ~/.docker/cli-plugins/ | By hand | No root, or you want a newer release for yourself only |
| Manual, all users | /usr/local/lib/docker/cli-plugins/ | By hand | No repo package for your distro or arch, air-gapped hosts |
Every route assumes Docker Engine and the docker CLI are already on the box, since Compose is only a plugin for that CLI. On Ubuntu and Debian with Docker’s apt repo, the Docker and Compose install for Ubuntu and Debian sets up both in one go, and Ubuntu 26.04 has its own Compose walkthrough for 26.04. Linux Mint users can follow the Mint Docker guide instead.
Install Compose from Docker’s repo on Rocky Linux and RHEL
Rocky Linux 10 has no Docker or Compose package of its own. AppStream ships Podman, and a search for *compose* on a fresh VM only turned up composefs and osbuild-composer, neither of which is what you want. Add Docker’s RHEL repository first. The same repo file works on RHEL, Rocky Linux and AlmaLinux:
sudo dnf -y install dnf-plugins-core
sudo dnf config-manager --add-repo https://download.docker.com/linux/rhel/docker-ce.repo
Before installing anything, ask dnf what the repo offers. Docker rebuilds this package for every Compose release, so the version here tells you whether the repo is current for your release of RHEL.
dnf -q info docker-compose-plugin
On our Rocky VM the package matched the newest upstream release on the day it shipped, built for el10 and served from docker-ce-stable.
Available Packages
Name : docker-compose-plugin
Version : 5.7.1
Release : 1.el10
Architecture : x86_64
Size : 8.8 M
Source : docker-compose-plugin-5.7.1-1.el10.src.rpm
Repository : docker-ce-stable
Summary : Docker Compose plugin for the Docker CLI
URL : https://github.com/docker/compose
License : Apache-2.0
Description : Docker Compose (V2) plugin for the Docker CLI.
:
: This plugin provides the 'docker compose' subcommand.
:
: The binary can also be run standalone as a direct replacement for
: Docker Compose V1 ('docker-compose').
That last line of the description is the reason the migration section further down works: the plugin binary still behaves as docker-compose when you call it by that name. Install the engine, CLI, containerd, Buildx and Compose together:
sudo dnf -y install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
dnf pulls in container-selinux as a dependency, so SELinux stays in enforcing mode and nothing here asks you to relax it. Buildx comes along because current Compose hands image builds to it.
Installed:
container-selinux-4:2.246.0-1.el10.noarch
containerd.io-2.4.2-3.el10.x86_64
docker-buildx-plugin-0.38.1-1.el10.x86_64
docker-ce-3:29.9.3-1.el10.x86_64
docker-ce-cli-1:29.9.3-1.el10.x86_64
docker-ce-rootless-extras-29.9.3-1.el10.x86_64
docker-compose-plugin-5.7.1-1.el10.x86_64
Complete!
Start the daemon now and on every boot, then add your account to the docker group so you don’t need sudo for every Compose command. Membership in that group is root-equivalent on the host, so only add people who could have root anyway:
sudo systemctl enable --now docker
sudo usermod -aG docker $USER
Log out and back in, or open a new SSH session, because group membership is read at login. Then confirm the version and where the package put the plugin.
docker compose version
rpm -ql docker-compose-plugin | grep cli-plugins
You should see the Compose release on the first line and the system plugin path on the second. The capture below also shows a package listing and a dnf upgrade that finds nothing newer, which is what a current install looks like:

Packaged Compose lives in /usr/libexec/docker/cli-plugins. Keep that path in mind, because a manual copy in your home directory will beat it, as the Debian test below shows. Fedora uses a different repo file; take it from Docker’s Compose plugin install page, which links the per-distro repository steps.
Check what your distro package gives you
Debian ships its own Docker build as docker.io and Compose as docker-compose, and there is no docker-compose-plugin package in its archive at all. Ask apt before you install either, because the Compose it offers is a long way behind upstream.
apt-cache policy docker.io docker-compose docker-compose-plugin
On Debian 13 the policy lists two packages and prints nothing for the third, which confirms the plugin package is not there. The engine is a 26.x build and Compose a 2.x build, so a recent compose.yaml may use features this pair does not know about.
docker.io:
Installed: (none)
Candidate: 26.1.5+dfsg1-9+deb13u1
Version table:
26.1.5+dfsg1-9+deb13u1 500
500 mirror+file:/etc/apt/mirrors/debian.list trixie/main amd64 Packages
500 mirror+file:/etc/apt/mirrors/debian-security.list trixie-security/main amd64 Packages
docker-compose:
Installed: (none)
Candidate: 2.26.1-4
Version table:
2.26.1-4 500
500 mirror+file:/etc/apt/mirrors/debian.list trixie/main amd64 Packages
Install these only on a host without Docker CE, because docker.io conflicts with Docker’s own docker-ce and containerd.io packages. Installing both and checking the version gives you exactly that older release. Debian’s package also registers itself as a CLI plugin, so docker compose and docker-compose both work and both report the same thing:
sudo apt install -y docker.io docker-compose
sudo usermod -aG docker $USER
docker compose version
The packaged build reports a Debian revision suffix instead of a v tag, which is a quick way to tell it apart from an upstream binary. As on Rocky, log out and back in before the later steps, because docker info and docker compose up need the daemon socket and fail with permission denied until the new group membership is active.
Docker Compose version 2.26.1-4
The capture repeats the check after install, along with the two files the package owns. The plugin path is the same /usr/libexec/docker/cli-plugins the Docker RPM used on Rocky, so a package from either source lands in one place.

For plenty of stacks that packaged release is enough. If a compose.yaml you pulled from a project uses newer keys, or you simply want what upstream ships today, add the manual plugin on top. It does not touch the Debian package, and the next section shows why the two can live side by side.
Install the Compose CLI plugin manually for one user
Compose releases are single static binaries on GitHub, one per architecture, each with its own .sha256 file. The asset names use the kernel’s machine name (x86_64, aarch64), so uname -m picks the right one. Start by looking up the latest release tag and your architecture:
COMPOSE_VERSION=$(curl -fsSL https://api.github.com/repos/docker/compose/releases/latest | grep '"tag_name"' | cut -d '"' -f4)
ARCH=$(uname -m)
echo "${COMPOSE_VERSION} ${ARCH}"
Both values should be filled in. An empty tag means the GitHub API call failed, usually rate limiting on a shared IP, and the downloads below would then fail with a 404. Fix that before going on, because every later command builds its URL from these two values.
v5.7.1 x86_64
To pin a particular release instead, set COMPOSE_VERSION to any tag from the Compose releases page, including the leading v. Now download the binary and its checksum straight into your per-user plugin directory. If you set DOCKER_CONFIG to move the Docker client config, use $DOCKER_CONFIG/cli-plugins instead, since that is where the CLI then looks.
mkdir -p ~/.docker/cli-plugins
cd ~/.docker/cli-plugins
curl -fsSLO "https://github.com/docker/compose/releases/download/${COMPOSE_VERSION}/docker-compose-linux-${ARCH}"
curl -fsSLO "https://github.com/docker/compose/releases/download/${COMPOSE_VERSION}/docker-compose-linux-${ARCH}.sha256"
Verify the download before you make it executable. The .sha256 file names the asset it describes, so sha256sum -c checks the right file without any copying of hashes:
sha256sum -c docker-compose-linux-${ARCH}.sha256
Anything other than OK means stop and download again. The troubleshooting section shows what a failed check looks like.
docker-compose-linux-x86_64: OK
Docker only loads plugins named docker-<command>, so rename the binary to docker-compose, make it executable and drop the checksum file:
mv docker-compose-linux-${ARCH} docker-compose
chmod +x docker-compose
rm docker-compose-linux-${ARCH}.sha256
cd
docker compose version
The version now matches the tag you downloaded. No sudo was needed at any point, because everything lives in your home directory.
Docker Compose version v5.7.1
The whole sequence on the Debian 13 VM looked like this, checksum line included:

COMPOSE_VERSION and ARCH only live in the current shell. If you come back later in a new session to upgrade or install system-wide, run the three lookup lines again first.
Confirm which Compose binary Docker runs
That Debian VM still had the packaged Compose in /usr/libexec/docker/cli-plugins, yet docker compose reported the new release. The copy in ~/.docker/cli-plugins wins for your account, while root and every other user keep the system copy. Ask the Docker CLI which file it loaded:
docker info --format '{{range .ClientInfo.Plugins}}{{if eq .Name "compose"}}{{.Path}} {{.Version}}{{end}}{{end}}'
It prints the plugin path and version that docker compose will use for the current user.
/home/josphat/.docker/cli-plugins/docker-compose v5.7.1
Run the version check as yourself, through sudo, and through the old docker-compose name, and you get two different answers on the same host:

That split is useful for trying a new release without touching anyone else, and a trap on shared servers: a cron job or systemd unit running as root keeps the old Compose while your shell tests the new one. If root needs the new release too, install it system-wide instead of per user.
Install Compose system-wide on aarch64
A system-wide install goes into /usr/local/lib/docker/cli-plugins, which every account on the host reads, root included. The steps are the same on x86_64; we ran them on a Debian 13 arm64 VM because that’s where people grab the wrong asset. Check the architecture names first:
uname -m; dpkg --print-architecture
The kernel says aarch64 while Debian’s package tools say arm64. Compose release assets follow the kernel name, so use uname -m, never the dpkg value:
aarch64
arm64
This VM had Debian’s docker.io without docker-compose, so Compose was missing entirely and the Docker CLI said so:
docker: 'compose' is not a docker command.
See 'docker --help'
Set the release tag and architecture for this shell, then download both files to /tmp:
COMPOSE_VERSION=$(curl -fsSL https://api.github.com/repos/docker/compose/releases/latest | grep '"tag_name"' | cut -d '"' -f4)
ARCH=$(uname -m)
cd /tmp
curl -fsSLO "https://github.com/docker/compose/releases/download/${COMPOSE_VERSION}/docker-compose-linux-${ARCH}"
curl -fsSLO "https://github.com/docker/compose/releases/download/${COMPOSE_VERSION}/docker-compose-linux-${ARCH}.sha256"
sha256sum -c docker-compose-linux-${ARCH}.sha256
The checksum line names the aarch64 asset, proof you pulled the right build for this CPU.
docker-compose-linux-aarch64: OK
Create the system plugin directory and install the binary with the right mode in one step. install -m 0755 sets the permissions and the root ownership that a plain mv from /tmp would not:
sudo mkdir -p /usr/local/lib/docker/cli-plugins
sudo install -m 0755 docker-compose-linux-${ARCH} /usr/local/lib/docker/cli-plugins/docker-compose
rm docker-compose-linux-${ARCH} docker-compose-linux-${ARCH}.sha256
docker compose version
sudo docker compose version
Both your account and root now see the same release, which is the point of the system-wide path.
Docker Compose version v5.7.1
Docker Compose version v5.7.1
Running file on the installed plugin confirms an ARM aarch64 executable, which rules out an architecture mix-up before it bites you in a deploy script:

On x86_64 and aarch64 the uname -m value matches the asset name exactly, so the block needs no edits on either. The same holds for ppc64le, s390x and riscv64. Only 32-bit ARM boards need ARCH set by hand, because upstream drops the trailing letter the kernel adds there. The Linux assets on the release page are:
docker-compose-linux-x86_64anddocker-compose-linux-aarch64docker-compose-linux-armv7anddocker-compose-linux-armv6for 32-bit ARMdocker-compose-linux-ppc64le,s390xandriscv64
We only ran the x86_64 and aarch64 builds. Each of the others ships its own .sha256 file, so the same checksum step applies.
Run a test stack
A version string proves the plugin loads, not that it can talk to your Docker daemon. Two small services are enough to exercise networking and port publishing. Create a project directory and a Compose file. Minimal cloud images may ship only vi, so swap in vi or nano if vim is missing.
mkdir -p ~/demo && cd ~/demo
vim compose.yaml
Add an nginx web service that depends on a Redis cache:
services:
web:
image: nginx:alpine
ports:
- "8080:80"
depends_on:
- cache
cache:
image: redis:alpine
Bring the stack up in the background. The -d flag returns your prompt once the containers start instead of streaming their logs.
docker compose up -d
Compose creates a project network named after the directory, then starts cache before web because of depends_on. With the images already pulled, the output looks like this:
Network demo_default Creating
Network demo_default Created
Container demo-cache-1 Creating
Container demo-cache-1 Created
Container demo-web-1 Creating
Container demo-web-1 Created
Container demo-cache-1 Starting
Container demo-cache-1 Started
Container demo-web-1 Starting
Container demo-web-1 Started
Check both containers and hit the published port. A container that exits straight after starting still shows in up output, so ps is the real test.
docker compose ps
curl -sI http://localhost:8080 | head -2
Both services should be Up, and nginx should answer with a 200:

That run used the manually installed plugin against Debian’s older packaged engine, and the same file came up on the Rocky VM with SELinux enforcing and on the arm64 VM with arm64 images. When you’re done, docker compose down removes the containers and the network but keeps the pulled images. For the day-to-day commands after this point, the Docker cheat sheet and the guide on managing containers with Docker Compose pick up where this leaves off.
Migrate from the standalone docker-compose binary
If you followed older instructions, including an earlier version of this page, you have a standalone binary at /usr/local/bin/docker-compose. It keeps working, but it never updates with the plugin, and it sits earlier in PATH than anything a package installs. Find out what docker-compose resolves to and compare it with the plugin:
which docker-compose
docker-compose version
docker compose version
On the Rocky VM the old binary was three major releases behind the plugin installed from Docker’s repo on the same host:
/usr/local/bin/docker-compose
Docker Compose version v2.28.1
Docker Compose version v5.7.1
Scripts and CI jobs that still call docker-compose don’t need rewriting. Replace the old file with a symlink to the plugin, so both names run one binary and upgrade together. On a packaged install the target is /usr/libexec/docker/cli-plugins/docker-compose:
sudo rm /usr/local/bin/docker-compose
sudo ln -s /usr/libexec/docker/cli-plugins/docker-compose /usr/local/bin/docker-compose
hash -r
docker-compose version
For a manual system-wide install, point the link at /usr/local/lib/docker/cli-plugins/docker-compose instead. We checked that variant on the arm64 VM, and it reported the same release. hash -r clears the shell’s cached path, otherwise the current session may keep running the deleted file. The old name now reports the plugin’s release:

Shell completion files from the old guides (/etc/bash_completion.d/docker-compose pulled from the Compose repo’s master branch) belong to the long-retired Python Compose. Delete them; the completion that ships with the docker CLI already covers docker compose subcommands.
Upgrade or remove Compose
How you upgrade depends on the route you took. A repo install upgrades with dnf (or apt on Docker’s Debian and Ubuntu repo), and it reports Nothing to do. when you’re already on the newest build:
sudo dnf -y upgrade docker-compose-plugin
Manual installs never update themselves. Re-run the lookup and download steps from the per-user or system-wide section: the API call picks up the new tag, the checksum guards the download, and the rename or install overwrites the old binary in place. Pin to a known tag on production hosts and upgrade on purpose, because a new Compose major can change output formats that scripts parse.
Removing a manual install is a single rm. Delete the per-user copy and Docker falls back to whatever system plugin remains, which on the Debian VM was the packaged release:
rm ~/.docker/cli-plugins/docker-compose
docker compose version
The fallback shows up immediately, with no restart of the Docker daemon, because the CLI looks for plugins on every call.
Docker Compose version 2.26.1-4
For the system-wide copy, run sudo rm /usr/local/lib/docker/cli-plugins/docker-compose, and remove the /usr/local/bin/docker-compose symlink if you made one. A packaged plugin comes out with the package manager:
sudo dnf -y remove docker-compose-plugin
On the Rocky VM, which still had the migration symlink in place, the removal took both commands away at once. Docker Engine’s own CLI words the missing plugin differently from Debian’s older build, and the dangling symlink makes the shell report the old name as missing:
docker: unknown command: docker compose
Run 'docker --help' for more information
bash: line 1: docker-compose: command not found
The line 1: prefix comes from running the check over a non-interactive SSH command; in a normal login shell bash prints the message without it. Delete /usr/local/bin/docker-compose as well when you remove the plugin for good. Removing Compose leaves your containers, volumes and images alone, so run docker compose down in each project first if you want the stacks gone too.
Fix common Docker Compose install errors
All three errors below came up on the lab VMs while testing this guide, and each has a different cause even when the message looks the same.
Error: “docker: ‘compose’ is not a docker command”
The Docker CLI found no working docker-compose plugin. That wording comes from the older Docker CLI that Debian packages, while the current CLI from Docker’s repo says docker: unknown command: docker compose for the same problem. Three causes produced it in testing:
- no Compose installed at all (Debian’s
docker.iowithoutdocker-compose) - the binary saved under its asset name instead of
docker-compose, or without the execute bit - a wrong-architecture binary in
~/.docker/cli-plugins
The third one is nasty. On the arm64 VM, an x86_64 build in the per-user directory made docker compose disappear even though a good aarch64 copy sat in /usr/local/lib/docker/cli-plugins. The broken user copy shadows the working system one, and only docker info says why:

Run docker info 2>&1 | grep 'not valid' whenever the subcommand vanishes. Delete or replace whatever plugin it names, and the next copy in line takes over straight away.
Error: “cannot execute binary file: Exec format error”
You get this when you run the plugin file directly and it was built for another CPU. It is the same mix-up as above seen from the shell. Check uname -m, download the asset whose name ends in that exact string, and confirm with file before installing it.
Error: “sha256sum: WARNING: 1 computed checksum did NOT match”
The file on disk isn’t the asset the .sha256 file describes. We triggered it on purpose by saving the aarch64 binary under the x86_64 name:
docker-compose-linux-x86_64: FAILED
sha256sum: WARNING: 1 computed checksum did NOT match
In real life the usual causes are a truncated download, a proxy that returned an HTML error page, or variables left over from another shell pointing at a different version or architecture. Delete both files, run echo "${COMPOSE_VERSION} ${ARCH}" to check the values, and download again. Never install a binary that failed the check. If you want a printed reference for Compose and the rest of the container toolchain, our list of the best Docker books covers the titles that keep up with the plugin era.
This helped me a lot and saved my day. Thank you Josphat!
Muito obrigado por compartilhar seu conhecimento de forma gratuita !
Nos estudantes no inicio do aprendizado nos beneficiamos muito com estes conteudo de bom nivel de informaçao .
bienvenida!
FYI – “grep docker-compose-linux-x86_64” did not work for my Raspberry Pi 4 Debian Linux setup. I worked around by replacing the “x86_64” “docker-compose” file with the AARCH file from the GIT for Docker Compose.
Good point.
It worked as & got my foot in the door, thanks!!
Awesome welcome.
Thanks G. Works Like a Charm
Awesome!