Plenty of tutorials still tell you to type docker-compose with a hyphen, and that command belongs to a version Docker stopped supporting after June 2023. The current command has a space in it. Getting it onto your machine works through Docker Desktop, the docker-compose-plugin package on Linux, or the standalone binary.
Docker Desktop’s release notes (Docker, 2026) list Compose v5 arriving in version 4.56.0 on January 12, 2026. The version number jumped from v2 to v5, but the command stayed docker compose. Developers run it on Windows, macOS, and Linux hosts, and Docker Engine and the Docker CLI have to be there first.
What Is Docker Compose?
One YAML file describes every container an application needs, and one command, docker compose up, creates and starts all of them on a single Docker host.
The file declares services, which get one entry per container and are built from an image or a Dockerfile. It also declares the private networks that let those services reach each other by name. Volumes sit alongside them for storage that survives container restarts.
Each service runs as one or more Docker containers, and Compose asks Docker Engine to create them. It never runs a container on its own.
The file format follows the Compose Specification, and Docker, Inc. maintains the tool. If the first docker compose up fails with a parse error, it’s usually an indentation slip, and a YAML validator catches those before you ever start the stack.
Compose stays on one host. Anything that spans several machines needs a different orchestrator.
What Is the Difference Between docker compose and docker-compose?
Docker ended support for the hyphenated docker-compose after June 2023, because it runs the retired Compose v1. The spaced version, docker compose, is a Docker CLI plugin written in Go, and it runs Compose v2 and later.
A few dates help place all of this.
- Docker set the end of Compose v1 support at June 2023 (Docker, 2022).
- GitHub began removing Compose v1 from its hosted runner images on July 29, 2024, after announcing the change on July 9 and then rescheduling the rollout (GitHub Changelog and runner-images issue #9692, 2024).
- Docker Desktop 4.56.0 shipped Compose v5 on January 12, 2026 (Docker Desktop release notes, 2026).
- The docker/compose releases page listed v5.5.1 as the latest release in September 2026 (GitHub, 2026).
Compose v2 and later (plugin)
The Docker CLI hosts the compose subcommand, which is why the syntax reads docker compose. Docker rewrote Compose in Go, and the team credited that move with faster feature delivery. The name never changed even as the version went from v2 to v5.
Docker Desktop’s release notes tie Compose v5 to a new official Go SDK. Other programs can use it to load, validate, and manage Compose projects without calling the CLI at all.
On every new machine, just type docker compose.
Compose v1 (retired)
The hyphen command still fills old tutorials. New setups shouldn’t touch it.
GitHub is the documented case. Its hosted runner images dropped Compose v1 in a rollout that began on July 29, 2024, and any workflow in GitHub Actions that still called docker-compose had to switch to docker compose (GitHub Changelog, 2024).
Docker dates the end of v1 support to after June 2023, while GitHub’s notice says v1 has been deprecated as of July 2023. The wording is a month apart and the instruction is the same: move to Compose v2.
Old scripts need two fixes. Replace docker-compose with docker compose in shell scripts and CI workflow files. And remove the unofficial docker-compose and docker-compose-v2 distro packages before installing Docker’s own, since Docker’s Ubuntu instructions list both as conflicting.
What Are the Requirements Before Installing Docker Compose?
You need a running Docker Engine, the Docker CLI, and permission to run Docker commands through sudo or the docker group. Windows adds a WSL 2 or Hyper-V backend, and Docker Desktop bundles the engine and CLI so you get them for free there.
Order matters on Linux. Install Docker Engine and the CLI before the plugin package, because the plugin adds a subcommand to a CLI that already exists. The daemon should be running too, with systemd managing it. On Windows, WSL 2 is the default backend and Hyper-V is the alternative.
A host without Docker Engine needs a fresh Docker installation before any plugin command works.
After that, checking whether Docker is running takes one command. sudo systemctl status docker shows the daemon state, and sudo systemctl start docker starts it when it’s stopped.
Docker’s Engine documentation notes that the docker group exists after installation but holds no users, so every command needs sudo until you add your account (Docker documentation, 2026).
| System | Supported releases | Notes |
|---|---|---|
| Ubuntu | 26.04, 24.04, 22.04 (LTS, 64-bit) | x86\_64, armhf, arm64, s390x, ppc64le |
| Fedora | 44 and 43 | rpm repository, dnf |
| Windows 11 | Enterprise, Pro, or Education 23H2 (build 22631) or higher | WSL 2 turned on |
| Debian, CentOS Stream, RHEL | Listed on Docker’s Engine install pages | Same repository method |
Release lists come from Docker’s Engine and Desktop install pages as of September 2026 (Docker documentation, 2026).
Which Docker Compose Installation Method Should You Choose?
Docker recommends Docker Desktop, which bundles Compose, Docker Engine, and the Docker CLI. On Linux servers the docker-compose-plugin package from Docker’s apt or dnf repository fits best. The standalone binary is a legacy option kept for backward compatibility.
| Method | Supported systems | Update path | Best fit |
|---|---|---|---|
| Docker Desktop | Windows, macOS, Linux | Docker Desktop updates | Laptops and workstations |
| Compose plugin package | Linux only | apt or dnf upgrade | Servers and CI hosts |
| Standalone binary (legacy) | Linux, Windows Server | Manual replacement | Locked-down or air-gapped hosts |
Docker Desktop wins on a laptop. On a server I’d pick the plugin package every time, since Desktop adds a desktop app and a licensing question to a host that only needs the CLI plugin.
Desktop’s upside is that Compose, Engine, and the CLI arrive in one step on Windows, macOS, and Linux. The catch is licensing. Commercial use at a company above 250 employees or $10 million in annual revenue needs a paid subscription (Docker documentation, 2026). The Compose version is also tied to the Desktop release, so you get whatever that build ships.
The plugin package upgrades with the same apt or dnf commands as everything else on the box, and there’s no desktop app to look after. It only runs on Linux, and Docker Engine has to be installed already.
The standalone binary works on hosts with no package repository access. Docker marks it as not recommended, and manual installs don’t auto-update.
How Do You Install Docker Compose on Ubuntu and Debian?
Set up Docker’s apt repository, then install the docker-compose-plugin package with apt. The repository supports Ubuntu 26.04, 24.04, and 22.04, and Debian follows the same steps with the repository URLs swapped.
- Remove conflicting unofficial packages with
sudo apt remove $(dpkg --get-selections docker.io docker-compose docker-compose-v2 docker-doc docker-buildx podman-docker containerd runc | cut -f1) - Add Docker’s GPG key and apt repository with the commands below
- Install the packages with
sudo apt install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin - Confirm the daemon runs with
sudo systemctl status docker - Verify Compose with
docker compose version
Here’s the repository setup for step two on Ubuntu.
# Add Docker's official GPG key:
sudo apt update
sudo apt install ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc
# Add the repository to Apt sources:
sudo tee /etc/apt/sources.list.d/docker.sources <<EOF
Types: deb
URIs: https://download.docker.com/linux/ubuntu
Suites: $(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}")
Components: stable
Architectures: $(dpkg --print-architecture)
Signed-By: /etc/apt/keyrings/docker.asc
EOF
sudo apt updateOn Debian, replace ubuntu with debian in the GPG key URL and the repository URL, and check Docker’s Debian page for the exact suite line. A host that already runs Docker Engine skips to the package step: sudo apt-get update, then sudo apt-get install docker-compose-plugin (Docker documentation, 2026).
A few things trip people up here. Docker doesn’t officially support Linux Mint and similar Ubuntu derivatives, although the steps can still work. The repository line reads UBUNTU\_CODENAME first and falls back to VERSION\_CODENAME, which is how a derivative resolves to its Ubuntu base release.
Skipping the chmod a+r line leaves apt unable to read the key, so it can’t verify the repository. And anything outside x86\_64, armhf, arm64, s390x, and ppc64le is off Docker’s supported architecture list.
How Do You Install Docker Compose on Fedora, CentOS Stream, and RHEL?
Add Docker’s rpm repository with dnf, install docker-compose-plugin, and start the daemon with systemd. Docker’s Engine documentation supports Fedora 44 and 43, and CentOS Stream and RHEL follow the same flow with their own repository files.
Fedora uses https://download.docker.com/linux/fedora/docker-ce.repo, CentOS Stream uses https://download.docker.com/linux/centos/docker-ce.repo, and RHEL uses https://download.docker.com/linux/rhel/docker-ce.repo.
On Fedora the repository command is sudo dnf config-manager addrepo --from-repofile https://download.docker.com/linux/fedora/docker-ce.repo. The install command is sudo dnf install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin.
Docker’s CentOS and RHEL pages give the exact repository command for each release. Docker’s Compose page lists sudo yum update and sudo yum install docker-compose-plugin for RPM-based systems, and yum is an alias for dnf on current releases.
When dnf asks about the GPG key on Fedora, the fingerprint must read 060A 61C5 1B55 8A7F 742B 77AA C52F EB6B 621E 9F35 before you accept it (Docker documentation, 2026).
Installing the packages doesn’t start Docker. Run sudo systemctl enable --now docker to start it and keep it starting at boot. To start the Docker daemon for one session only, use sudo systemctl start docker instead.
If the service fails and journalctl -u docker reports “failed to find iptables”, run sudo alternatives --set iptables /usr/bin/iptables-nft and restart the service. Fedora releases other than 44 and 43 sit outside Docker’s supported list, and RHEL minor releases follow the list on Docker’s RHEL page.
How Do You Install Docker Compose on Windows 11 and macOS?
Download Docker Desktop for Windows or macOS and run the installer. Compose ships inside the bundle, so no separate install step exists, and the About Docker Desktop entry in the Docker menu shows the bundled Compose version.
On Windows 11, WSL 2 is the default backend. It installs per user without administrator privileges, although turning on the WSL 2 feature for the first time needs an administrator once, and it has to be on before the first launch. Hyper-V is available only with an all-users installation. The Windows Server service (LanmanServer) must also be running with its start mode set to Automatic.
On macOS, run the Docker Desktop installer for your chip, then open the app once so it finishes setup. Open a terminal afterward and run docker compose version.
Both platforms run Linux containers inside a lightweight virtual machine. On Windows that machine needs hardware virtualization turned on in firmware.
Docker Desktop’s paid-subscription rule for larger companies applies on both platforms, so check company size before rolling it out to a team.
How Do You Install the Standalone Docker Compose Binary?
Download the release binary that matches your operating system and CPU architecture from the docker/compose repository on GitHub, make it executable, and put it on the PATH. Placed in a CLI plugins directory instead, the same file runs as docker compose.
Getting the file is one download from GitHub, and the releases page lists a sha256 digest next to each asset so you can verify the copy.
On Linux, it goes like this.
- Download the binary:
sudo curl -SL https://github.com/docker/compose/releases/download/v5.5.0/docker-compose-linux-x86_64 -o /usr/local/bin/docker-compose - Make it executable:
sudo chmod +x /usr/local/bin/docker-compose - Test it:
docker-compose version - If the shell cannot find it, link it into a directory on the PATH:
sudo ln -s /usr/local/bin/docker-compose /usr/bin/docker-compose
Docker’s pages pin v5.5.0 in the download URL, while the GitHub releases page lists v5.5.1 as the latest release (Docker documentation and GitHub, 2026). Change the version in the URL to get the newer build, and swap x86\_64 for the architecture you need.
The same file can live in three places. At /usr/local/bin/docker-compose it runs as the standalone docker-compose. Put it at $DOCKER_CONFIG/cli-plugins/docker-compose and it becomes docker compose for one user. Put it at /usr/local/lib/docker/cli-plugins/docker-compose and every user gets docker compose.
The per-user path assumes DOCKER\_CONFIG points at ~/.docker, which is the default.
A hyphen command isn’t proof of Compose v1. Docker’s standalone page installs a current release under that name, so docker-compose version shows which generation you actually have.
Windows Server has its own route.
- Open PowerShell as an administrator and approve the prompt
- On older releases such as Windows Server 2016, turn on TLS 1.2 first, because GitHub requires it:
[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12 - Download the executable:
Start-BitsTransfer -Source "https://github.com/docker/compose/releases/download/v5.5.0/docker-compose-windows-x86_64.exe" -Destination $Env:ProgramFiles\Docker\docker-compose.exe
On Windows Server 2019, $Env:ProgramFiles\Docker already sits in the system PATH, so docker-compose.exe version works right away.
For an offline host, download the binary on a connected machine and copy it over to the air-gapped one. Compare its digest with sha256sum docker-compose-linux-x86_64 before you run the chmod step.
Three failures come up most. A binary built for another CPU refuses to execute. Writing into /usr/local/bin without sudo is refused. And on networks that filter github.com the download never starts.
How Do You Verify the Docker Compose Installation?
Run docker compose version. A working install prints one line in the format Docker Compose version vX.Y.Z, and a small test project then proves the connection to the Docker daemon.
Use docker-compose version instead if you installed the standalone binary. To see which plugin the CLI actually loaded, docker info --format '{{range .ClientInfo.Plugins}}{{if eq .Name "compose"}}{{.Path}}{{end}}{{end}}' prints its path. The real proof is running docker compose up -d against a test file and watching a service start.
Save this as compose.yaml.
services:
web:
image: nginx
ports:
- "8080:80"docker compose ps lists the running service, and curl http://localhost:8080 returns the nginx welcome page. docker compose down stops and removes the service when the test is done.
The Compose Specification accepts 4 filenames and prefers one (Compose Specification, as of September 2026).
compose.yaml(preferred)compose.ymldocker-compose.yaml(backward compatibility)docker-compose.yml(backward compatibility)
When both compose.yaml and a legacy name sit in one directory, Compose reads compose.yaml. A YAML cheat sheet helps with the syntax of the file itself.
Old files with a top-level version: line still run. Compose treats the field as obsolete, prints a warning, and validates against the most recent schema either way (Docker documentation).
Commands beyond up, ps, and down are collected in a Docker cheat sheet.
How Do You Fix Docker Compose Installation Errors?
Most installation errors come down to a missing plugin or the wrong syntax, an account that can’t reach the Docker socket, or apt and dnf failing to verify Docker’s repository key. Each has a specific fix.
Command not found
| Error | Cause | Fix |
|---|---|---|
| docker: ‘compose’ is not a docker command | No Compose plugin in any CLI plugins directory | Install docker-compose-plugin, or copy the binary into a cli-plugins directory |
| docker-compose: command not found | Only the plugin exists, so the hyphen command does not | Type docker compose, or install the standalone binary |
| Binary installed, shell cannot find it | File sits outside the PATH | Link it into /usr/bin with ln -s |
A plugin copied into one user’s ~/.docker/cli-plugins stays invisible to every other account. Use the all-users directory when several people share the host.
Permission denied
The Docker daemon socket belongs to root, and only members of the docker group reach it without sudo.
- Create the group if it is missing:
sudo groupadd docker - Add your account:
sudo usermod -aG docker $USER - Log out and back in, or run
newgrp dockerto activate the change - Confirm with
docker run hello-world
Docker’s documentation warns that the docker group grants root-level privileges to its members, which is a real cost on shared machines. Rootless mode is the alternative when that trade-off is unacceptable.
If you ran Docker commands with sudo before joining the group, a config.json permission warning can appear. Fix it with sudo chown "$USER":"$USER" /home/"$USER"/.docker -R and sudo chmod g+rwx "$HOME/.docker" -R.
Repository key errors
On Ubuntu and Debian, confirm that the Signed-By path in /etc/apt/sources.list.d/docker.sources matches the key file, then download the key again and run sudo apt update.
On Fedora, CentOS Stream, and RHEL, reject the key when the fingerprint differs from the one on Docker’s install page for your distribution.
Docker’s documentation also warns that re-running the convenience script can break hosts where the repository already exists, so upgrade through the package manager instead.
A clean reset removes /etc/apt/sources.list.d/docker.sources and /etc/apt/keyrings/docker.asc, then repeats the repository setup.
How Do You Update and Uninstall Docker Compose?
Update the Compose plugin through the package manager that installed it, replace a manual binary with a newer download, and remove the plugin with apt-get remove or yum remove. Docker Desktop updates and removes Compose together with the whole application.
- On apt systems,
sudo apt-get install --only-upgrade docker-compose-pluginupgrades the package without touching anything else - On dnf systems,
sudo dnf upgrade docker-compose-plugindoes the same - For a manual binary, download the new release over the old file and repeat the chmod step
- With Docker Desktop, update the app and the bundled Compose follows
Docker’s own update instructions simply repeat the install commands, and both routes end at the same result.
To uninstall, the command depends on how Compose got there.
sudo apt-get remove docker-compose-pluginon Ubuntu and Debiansudo yum remove docker-compose-pluginon RPM-based systemsrm $DOCKER_CONFIG/cli-plugins/docker-composefor a manual per-user installrm /usr/local/lib/docker/cli-plugins/docker-composefor a manual all-users install
A Permission denied error on either rm command means you lack write access, and prefixing sudo forces the removal. A standalone binary is deleted from the directory where you placed it, usually /usr/local/bin.
Run docker compose down in each project directory before removal. It stops and removes that project’s containers and networks, and named volumes stay unless you add -v.
Removing the plugin leaves images, containers, and volumes from past projects in place. Clean them with docker commands, starting with a guide to removing Docker images.
Uninstalling Docker Desktop removes all Docker components, including Docker Engine, the Docker CLI, and Compose, unless another Docker instance exists on the machine (Docker documentation).
A Compose v1 copy installed through pip needs pip uninstall docker-compose.
When Does This Docker Compose Installation Not Apply?
These routes fail on multi-host clusters, on Podman hosts that call an external Compose provider, on Windows Server without Docker Desktop, and on networks that block download.docker.com or github.com. Each case calls for a different tool or method.
| Situation | Why it fails | What to use |
|---|---|---|
| Cluster of several machines | Compose targets one Docker host | A Swarm cluster, or Compose Bridge for Kubernetes |
| Podman host | podman compose delegates to an external provider | docker-compose or podman-compose as the provider |
| Windows Server | Docker Desktop is not the route | The standalone binary |
| Blocked network | Repository and release downloads never arrive | The offline copy method |
Docker’s production guidance calls a single server the easiest deployment and points to a Swarm cluster for scaling up. Compose Bridge converts a Compose file into configuration for platforms such as Kubernetes, and a comparison of Kubernetes and Docker shows where each tool fits.
Podman’s documentation describes podman compose as a thin wrapper around an external provider, with docker-compose taking precedence when both providers are installed. The PODMAN\_COMPOSE\_PROVIDER variable or the compose\_providers setting picks a different one.
Windows Server is the one place Docker Desktop isn’t the answer. Docker’s standalone instructions cover servers that run the Docker daemon directly.
On restricted networks, the plugin package needs download.docker.com, and the manual and standalone routes need github.com. A host that reaches neither needs a binary copied in from another machine.
Where licensing rules out Docker Desktop, the plugin package or the standalone binary takes its place.
FAQ on How To Install Docker Compose
Is Docker Compose the same as Docker Swarm or Kubernetes?
No. Docker Compose runs multi-container applications on one Docker host from a YAML file. Swarm mode schedules services across a cluster of Docker Engines, and Kubernetes is a separate orchestrator that Compose Bridge can target.
Is Docker Desktop required to use Docker Compose?
No. Linux hosts get Compose through the docker-compose-plugin package next to Docker Engine, with no desktop app involved. Windows and macOS use Docker Desktop, and Windows Server uses the standalone binary.
Can Docker Compose be installed offline?
Yes. Download the docker-compose-plugin .deb or .rpm file from download.docker.com on a connected machine, copy it over, and install it with dpkg or dnf. A release binary copied from GitHub works the same way after a chmod.
Does Docker Compose run on a Raspberry Pi?
Yes. Docker’s Engine documentation includes a Raspberry Pi OS page, and the same repository method supplies docker-compose-plugin. For manual installs, pick the release asset that matches the board’s architecture, such as armv7 (32-bit) or aarch64 (64-bit).
Should an existing docker-compose setup move to docker compose?
Yes. Docker describes Compose v2 as a drop-in replacement for v1, and in most cases removing the dash is the whole change. Delete the obsolete top-level version: line as well, and Compose stops printing its warning.
Does Podman work with Compose files?
Yes, through podman compose, a thin wrapper around an external provider such as docker-compose or podman-compose. It prints a warning about running an external command, and setting PODMAN\_COMPOSE\_WARNING\_LOGS to false silences it.
What Should You Do First After You Install Docker Compose?
Start by finding out which Compose binary answers on the host. Then settle docker group access, and only after that pin the release version in your scripts. That order matters, because each step depends on the result of the one before it.
The plugin package trades Docker Desktop’s bundled convenience for repository upkeep. On a server with no desktop app, that upkeep is the price, and I think it’s a fair one.
Docker’s documentation, checked on September 28, 2026, supports this order. A new major release or a renamed docker-compose-plugin package would change it.
With Compose running, learning how to use Docker covers the image and container commands that every Compose project calls.
- MySQL Cheat Sheet - September 30, 2026
- How to Remove Duplicate Lines in Notepad++ (Sorted or Unsorted) - September 29, 2026
- Should Your Engineering Team Still Own the Marketing Website? - September 29, 2026
