Docker

Install Docker Compose on Any Linux Distro (Manual CLI Plugin)

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.

Original content from computingforgeeks.com - post 24552

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.

RouteBinary pathUpdatesUse it when
Docker repo, docker-compose-plugin/usr/libexec/docker/cli-plugins/With dnf or aptDocker CE is installed from download.docker.com
Distro package (Debian docker-compose)/usr/libexec/docker/cli-plugins/ plus /usr/bin/docker-composeWith 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 handNo root, or you want a newer release for yourself only
Manual, all users/usr/local/lib/docker/cli-plugins/By handNo 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:

Docker Compose plugin installed from Docker's dnf repository on Rocky Linux 10 with docker compose version output

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.

apt-cache policy on Debian 13 showing docker.io and docker-compose packages and no docker-compose-plugin package

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:

Manual per-user install of the Docker Compose CLI plugin on Debian 13 with sha256sum check passing

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:

User plugin in ~/.docker/cli-plugins overriding the Debian docker-compose package while sudo still sees the packaged version

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:

System-wide install of the aarch64 Docker Compose plugin into /usr/local/lib/docker/cli-plugins on Debian 13 arm64

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_64 and docker-compose-linux-aarch64
  • docker-compose-linux-armv7 and docker-compose-linux-armv6 for 32-bit ARM
  • docker-compose-linux-ppc64le, s390x and riscv64

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:

docker compose up and docker compose ps showing nginx and redis containers running with nginx answering HTTP 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:

Replacing an old standalone docker-compose binary in /usr/local/bin with a symlink to the Compose CLI plugin on Rocky Linux 10

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.io without docker-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:

x86_64 Compose plugin on an aarch64 host causing compose is not a docker command and an exec format error warning

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.

Keep reading

Best UI Applications for Managing Docker Containers Containers Best UI Applications for Managing Docker Containers Install Docker and Run Containers on Ubuntu 24.04|22.04 Containers Install Docker and Run Containers on Ubuntu 24.04|22.04 Install UniFi OS Server on Ubuntu 24.04 LTS Containers Install UniFi OS Server on Ubuntu 24.04 LTS OpenCloud vs ownCloud vs Nextcloud: Tested on Identical VMs Cloud OpenCloud vs ownCloud vs Nextcloud: Tested on Identical VMs Kiri Container Runtime on Linux: Install and Benchmark vs Docker Containers Kiri Container Runtime on Linux: Install and Benchmark vs Docker Woodpecker CI with Forgejo: Docker Compose Install and Pipelines Containers Woodpecker CI with Forgejo: Docker Compose Install and Pipelines

9 thoughts on “Install Docker Compose on Any Linux Distro (Manual CLI Plugin)”

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

    Reply
  2. 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.

    Reply

Leave a Comment

Press ESC to close