Install Docker Compose v2 on Linux Without Docker Desktop
Install the Compose v2 plugin from Docker's apt repository or the release binaries, then switch your scripts from docker-compose to docker compose.
Installing Docker, without Docker Desktop?
From the documentation:
Docker Compose is a tool for defining and running multi-container applications.
Compose v2 changed the command from docker-compose to docker compose, and it installs differently from v1. Instead of a standalone Python program, it ships as a plugin for the Docker CLI. This guide covers installing the plugin on Linux and moving off v1.
TL;DR: Already using Docker's apt repo? Run sudo apt install docker-compose-plugin, then docker compose version.
Docker Desktop bundles Compose, and that's how most people get it. On Linux it comes with conditions. The Ubuntu install page asks for:
an x86-64 system with Ubuntu 26.04 LTS or 24.04 LTS
That rules out older LTS releases, ARM machines, and most servers, which don't run a desktop environment at all. A few of my machines fall into those groups, so I install Docker Engine and the Compose plugin directly. Both are free and need neither Docker Desktop nor a recent distro.
Installing Docker and Docker Compose on Linux
Compose runs on top of Docker Engine, so we install both from Docker's apt repository. These commands follow Docker's Ubuntu guide, which supports Ubuntu 22.04, 24.04, 26.04 and 26.10.
On Debian 12 or 13, replace ubuntu with debian in both URLs (the GPG key and the repository). The rest of the steps are the same, and Docker's Debian guide covers it in full.
Add Docker's 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 your 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
Install Docker Engine with the Compose plugin:
$ sudo apt update
$ sudo apt install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
Check that both work:
$ sudo docker run hello-world
$ docker compose version
To run docker without sudo, add yourself to the docker group, then log out and back in so the change takes effect:
$ sudo usermod -aG docker $USER
Docker's Linux post-install steps explain what this group grants and cover starting Docker on boot.
Installing Docker Compose from binaries
If you already have Docker Engine but your distro isn't covered by Docker's repository, or you'd rather not add another apt source, install the Compose plugin from its release binary instead.
-
Create the plugin directory. Docker looks for CLI plugins in
/usr/local/lib/docker/cli-plugins, so a binary there works for every user on the machine:$ sudo mkdir -p /usr/local/lib/docker/cli-plugins -
Download the latest release straight into that directory as
docker-compose.$(uname -m)fills in your architecture (x86_64oraarch64), so the same command works on Intel and ARM machines:$ sudo curl -L "https://github.com/docker/compose/releases/latest/download/docker-compose-linux-$(uname -m)" \ -o /usr/local/lib/docker/cli-plugins/docker-composeOn 32-bit ARM, such as older Raspberry Pi OS installs,
uname -mprintsarmv7land no release file has that name. Replace$(uname -m)witharmv7.To pin a specific version, swap
latest/downloadfordownload/v5.7.0(or whichever tag you need from the release page). -
Make the file executable with
chmod +x:$ sudo chmod +x /usr/local/lib/docker/cli-plugins/docker-compose -
Verify that the installation was successful:
$ docker compose version Docker Compose version v5.7.0Compose releases have moved past 2.x, but every version from 2 onward is the same
docker composeplugin this guide covers.
Transitioning away from docker-compose (version 1)
Docker Compose V2 is a major version bump release of Docker Compose. It has been completely rewritten from scratch in Golang (V1 was in Python). Compose V1 reached end of life in 2023 and gets no more updates, including security fixes.
If you already have a pre-existing version of docker-compose (version 1), the installation of version 2 doesn't remove that legacy version:
$ docker-compose --version
docker-compose version 1.28.2, build 67630359
If you want to transition from that legacy docker-compose 1.xx to Compose V2, consider installing compose-switch to translate docker-compose ... commands into Compose V2's docker compose .... Post-transition, you can remove the legacy version and use Compose V2 exclusively.
If you have a local Compose file, you should now run docker compose up (instead of docker-compose up). For completeness' sake, an example Compose file looks like the following:
services:
web:
build: .
ports:
- "5000:5000"
volumes:
- .:/code
redis:
image: redis
Further learning resources on Docker
If you made it this far, a good "next step" is Stane's write-up on Docker and the official documentation:

Building agents that build your business
A two-evening workshop on designing and shipping AI agents that do real work for your business: from the agentic patterns that keep them reliable, to a working multi-agent system that researches, drafts and reports on your behalf.
December 9, 2026Zoom Conferencing (Online)
Keep reading

The Essential Guide to Docker
A Python developer's guide to get started with Docker, Docker-Compose and Docker Desktop

1. Overview & Setup | Build a Streaming Data Pipeline on open source stacks
In the first part of the article, we will discuss the overview of an open-source streaming data pipline and its environment setup using Docker Compose.
Streaming Data
2. OLTP and OLAP Databases | Build a Streaming Data Pipeline on open source stacks
In the second part of the article, we will walk through the design and implementation of OLTP and OLAP databases using Cassandra and MySQL respectively.
Field notes, straight to your inbox
We publish what we learn building analytics and AI systems for some of the largest enterprises in the region. Subscribe and we will send the next one your way.
