Setting up Docker Compose v.2 on Linux
Upgrading to Docker Compose V2 from legacy v1 without Docker Desktop
Feb 25, 2025 · Samuel Chan
Installing Docker, without Docker Desktop?
Straight from the documentation:
Docker Compose is a tool for running multi-container applications on Docker defined using the Compose file format. A Compose file is used to define how the one or more containers that make up your application are configured.
Version 2 of Docker Compose also uses a different syntax (docker compose ...
rather than docker-compose ...
), and the installation process for v2 also differs from that of v1. This guide is intended for developers wanting to install Docker Compose v2 and a quick start guide on using it effectively.
You will get Docker Compose by installing Docker Desktop and this is most likely how many Linux users would go about it. However, on some distributions, including Ubuntu, Docker Desktop will require user to have the latest LTS (long term support) version of its distro -- no small feat when this isn't always an option, such as in the case of a production machine.
Pulling from the documentation:
To install Docker Desktop successfully on Ubuntu, you must:
- Meet the system requirements
- Have a 64-bit version of either Ubuntu Jammy Jellyfish 22.04 (LTS) or Ubuntu Impish Indri 21.10. Docker Desktop is supported on x86_64 (or amd64) archi
On more than one of my machines, I'm using an older LTS -- which means I'm out of luck with Docker Desktop. This is the motivation of writing this guide on installing Docker and Docker Compose on Linux without the Docker Desktop bundle.
Installing Docker and Docker Compose on Linux
Docker Compose requires the use of Docker so a quick installation guide will be handy reference here.
First, set up Docker's repository and install them with cURL
is the recommended approach and this is done with the following lines of code:
Add Docker’s official GPG key and set up the repository
Finally, install Docker Engine and Docker Compose:
Verify the installation:
Installing Docker Compose from binaries
If you are restricted from updating to the latest versions of your Linux distro to meet the requirement of Docker Desktop, and would like to install from the provided binaries, read on!
-
Hop over to the release page and find the relevant binary for your OS. Firing up your terminal and using the
uname
command will help:Replace the following command with the latest version from the aforementioned release page and the appropriate kernel name. The following command uses
cUrl
to download that and store it to/usr/local/lib/docker/cli-plugins
, making it available system-wide:Rename it to
docker-compose
using themv
command:Skip to (3)!
-
(Alternative) You can also download the right binary for your distribution manually, rename it to
docker-compose
post-download and then copy it to/usr/local/lib/docker/cli-plugins
using thecp
ormv
(for 'move') command.- Create that directory if it doesn't yet exist before copying it over
-
Make the file executable with
chmod +x
: -
Verify that the installation was successful:
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).
If you already have a pre-existing version of docker-compose
(version 1), the installation of version 2 doesn't remove that legacy version:
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:
Further learning resources on Docker
If you make it this far, a good "next step" is Stane's write-up on Docker and the official documentation:
Read More
Tags: docker, docker compose