Last Updated:
A cabin cruiser docked next to a pier at sunrise

How to install the latest version of Docker Compose on Linux (and why you should)

David Rutland
David Rutland CLI

It's an understatement to say that Linux has a diverse software ecosystem. No two distros are identical, and each person's setup is unique to them in terms of both software and hardware.

While this is great if you want to express your individuality and indulge your curiosity by running the latest niche project on DistroWatch, it makes it difficult for developers to create software for a standard Linux environment - because there isn't one.

All software has dependencies that you need to have installed on your system before you can install certain packages. What those packages are, and what packages are available to you will vary wildly. If you're too far from 'the norm', or if the versioning isn't quite right, you could end up in dependency hell.

Use containers to create standard environments

Containerisation is the solution to situations where managing dependencies can become excessively complex, problematic, and error-prone.

Instead of creating and releasing a single app, developers while produce a container that includes everything the app needs to run. This can include pre-configured databases, dependencies pinned to a certain version, or even full-blown operating system bases.

While there are many container orchestration tools, Docker is the most commonly used, and the ancillary project, Docker Compose, allows you to define and run multi-container Docker applications. With Docker compose, you can manage any number of local or web-facing applications, with nothing more than a simple markup file, and some easy-to-recall commands.

Install Docker on Debian, Ubuntu, and Raspberry Pi OS

Docker is available in the standard repositories, and there are rarely any breaking changes from the most recent version (at least we've never heard of any ). To install Docker on any Debian derived system, open a terminal, and enter

sudo apt install

Docker runs as a privileged daemon, with root powers. You'll need to add your user to the Docker group in order to summon it:

sudo usermod -aG docker your_username

Now log out and back in again for the changes to take effect

Don't install Docker Compose from the default repository!

A sailing boat on file at a dock. The dock is also on fire

Docker compose is a different kettle of fish entirely, and while most projects will run just fine if you install Docker Compose with:

sudo apt install docker-compose

Some won't, and we've seen an increasing number of failures where deploying a project requires excessive workarounds. Rather than an orderly cargo port, you're faced with a burning shipwreck instead.

If you're running into inexplicable problems with deploying apps when using a repo-installed version of Docker Compose, first uninstall it:

sudo apt remove docker-compose

Visit the Docker Compose GitHub releases page, scroll down to Assets, and locate the correct package for your system architecture.

Assets section of the docker-compose releases page showing linux packages

If you're not sure, you can find out your system architecture by typing:

uname -m

...into a terminal.

In the case of our 64-bit Raspberry Pi 4B, this command will return aarch64, so we'd look for the docker-compose-linux-aarch64 package.

If you have a modern desktop or laptop, it's likely that you need docker-compose-linux-x86_64.

Download the relevant package, locate it in your terminal, then move it into your path:

mv docker-compose* /usr/local/bin/docker-compose

Now make it executable with:

sudo chmod +x /usr/local/bin/docker-compose

That's all you need to do. You now have the most recent Docker Compose version installed!

Use it to install and run some awesome self-hosted projects such as Immich - a better self-hosted Google Photos alternative, or host your own audiobook library with Audiobookshelf!