Installing Docker Compose on Ubuntu 22.04/20.04: Complete Guide

Introduction / Why This Is Needed

Docker Compose is a tool for defining and running multi-container Docker applications. With a simple YAML file, you can configure services, networks, and volumes, then launch everything with a single command.

After completing this guide, you will be able to:

• Deploy complex applications (e.g., web server + database) with one command.
• Manage the container lifecycle (start, stop, rebuild).
• Isolate environments for development, testing, and production.

Installation via the official Docker repository guarantees you get the latest version (v2) with regular updates and security patches.

Prerequisites / Preparation

Before you begin, ensure that:

1. You have Ubuntu 22.04 LTS or 20.04 LTS (this guide has been verified on these versions).
2. You have superuser privileges (sudo) to install packages.
3. Docker Engine is already installed and running.
   If Docker is not installed, first complete the guide to installing Docker on Ubuntu. You can verify with:

   docker --version
   

   
   Example output: Docker version 24.0.7, build afdd53b.
4. Your system is updated (recommended):

   sudo apt update && sudo apt upgrade -y
   

Step 1: Install Dependencies

Install curl to download the GPG key and gnupg to work with it:

sudo apt update
sudo apt install -y curl gnupg

💡 Tip: The ca-certificates package is usually already installed, but if you encounter SSL errors, install it: sudo apt install -y ca-certificates.

Step 2: Add Docker's Official GPG Key

Docker signs its packages with a GPG key. Add it to your system's keyring:

curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg

What the command does:

• curl -fsSL — a silent downloader that follows redirects.
• gpg --dearmor — converts the key from ASCII format to binary.
• The key is saved to /usr/share/keyrings/docker-archive-keyring.gpg — the standard location for APT keys.

Step 3: Add Docker's APT Repository

Add the Docker repository corresponding to your Ubuntu version:

echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

Command breakdown:

• $(dpkg --print-architecture) — automatically detects your architecture (amd64, arm64, etc.).
• $(lsb_release -cs) — detects your release codename (jammy, focal).
• The entry goes into /etc/apt/sources.list.d/docker.list — a separate file for third-party repositories.

Step 4: Install the Docker Compose Plugin

Now install the Docker Compose plugin itself:

sudo apt update
sudo apt install -y docker-compose-plugin

⚠️ Important: The package is named docker-compose-plugin (for v2). Do not confuse it with docker-compose (the legacy v1), which may be available in Ubuntu's default repositories.

After installation, Docker Compose will be available as a Docker CLI plugin: docker compose.

Step 5: Verify the Installation

Ensure the installation was successful:

docker compose version

Expected output (example):

Docker Compose version v2.24.5

If you see a version number, you're ready. If the command is not found, restart Docker:

sudo systemctl restart docker

Step 6: Configure Permissions (Optional)

By default, Docker and Docker Compose require root privileges. To use them without sudo:

1. Add your current user to the docker group:

   sudo usermod -aG docker $USER
   

2. Log out and back in to your system or run:

   newgrp docker
   

3. Verify:

   docker ps
   

   If there are no access errors, the configuration was successful.

⚠️ Warning: Being in the docker group grants privileges equivalent to root. Ensure you trust all users in this group.

Verification

Create a test project to verify everything works:

1. Create a directory and a docker-compose.yml file:

   mkdir ~/test-compose && cd ~/test-compose
   cat > docker-compose.yml <<EOF
   version: '3.8'
   services:
     hello-world:
       image: hello-world
   EOF
   

2. Run:

   docker compose up
   

3. You should see the hello-world image output and a success message.
4. Clean up:

   docker compose down
   

If everything works, Docker Compose is installed and configured correctly.

Troubleshooting

Error: docker: command not found after installation

Cause: PATH variable not updated or Docker not restarted.
Solution:

sudo systemctl restart docker
# Or reboot your system

Error: Got permission denied while trying to connect to the Docker daemon socket

Cause: User is not in the docker group.
Solution: Perform the permission configuration and log out/in.

Error: The repository does not have a Release file

Cause: Incorrect Ubuntu codename in the repository (e.g., using an unsupported version).
Solution: Ensure $(lsb_release -cs) returns jammy (22.04) or focal (20.04). For other Ubuntu versions, use the appropriate codenames from the Docker documentation.

docker-compose-plugin package not found

Cause: Docker repository not added or not updated.
Solution:

sudo apt update
# Check for the existence of /etc/apt/sources.list.d/docker.list
cat /etc/apt/sources.list.d/docker.list

If the file is empty or missing, repeat Step 3.

Conflict with an installed docker-compose (v1) from Ubuntu's repository

Cause: v1 and v2 are installed simultaneously.
Solution: Remove the old version:

sudo apt remove -y docker-compose

Keep only docker-compose-plugin.

Additional Resources

• Official Docker Compose documentation: docs.docker.com/compose
• docker compose reference: docker compose --help
• docker-compose.yml examples: github.com/docker/awesome-compose