Install Docker Compose on a Linux VPS in 2026

You have a fresh Ubuntu 24.04 VPS, Docker Engine is running, and now you need Docker Compose to spin up a multi-container stack. The quickest way to install Docker Compose on a Linux VPS is to enable the official Docker Compose plugin, which the apt package docker-compose-plugin installs for you. No manual downloads, no permission headaches, no guessing which binary is current. This guide walks through the install on Ubuntu 24.04 LTS, verifies every step, and fixes the two mistakes that break Compose for most people: a missing plugin and a wrong executable path.

Prerequisites

• A Linux VPS running Ubuntu 24.04 LTS (the commands also work on Debian 12, but paths and package names stay Ubuntu-specific here).
• A non-root user with sudo privileges. If you only have root, create one first: adduser deploy && usermod -aG sudo deploy.
• Docker Engine already installed and the docker service enabled. If not, install it from the official Docker apt repository, not from Ubuntu's universe.
• A domain or application stack that actually needs Compose. Single-container apps do not justify the extra layer.

Why use Docker Compose v2 instead of the standalone binary

Docker Compose v2 is a plugin to the Docker CLI, not a separate Python script. The old docker-compose (v1) is end-of-life and receives no security updates. The plugin ships as docker compose (no hyphen), installs from the same apt repository as Docker Engine, and tracks the Engine version. That means one source of truth for updates: apt upgrade updates both. On a VPS where you manage everything yourself, this matters. You do not want a hand-placed binary in /usr/local/bin going stale while the Engine moves on. The plugin also parses the same compose.yaml files, supports all the v2 features (profiles, include, watch), and gives you the same output format. There is no reason to install the standalone binary in 2026.

Step 1 - Installing Docker Engine from the official repository

Docker Compose will not install cleanly unless Docker Engine itself comes from the official Docker apt source. Ubuntu's own docker.io package works, but the Compose plugin version may lag behind. Set up the official repository first. This is the same procedure documented by Docker, and it is the only path that keeps Engine and plugin in sync.

sudo apt update
sudo apt install -y 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
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

The signed-by option pins the repository to the GPG key you just placed in /etc/apt/keyrings. Without it, apt accepts any key that signs the repo, which is a weaker trust model. The $(. /etc/os-release && echo "$VERSION_CODENAME") substitution resolves to noble on Ubuntu 24.04, so the repository line points at the correct release. Now install the Engine plus the Compose plugin together.

sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

Note the docker-compose-plugin package. That is what pulls in Compose v2. If you are upgrading an existing install, run the same command; apt will upgrade the plugin to the current version.

Verify that the Docker daemon is active before continuing.

sudo systemctl status docker --no-pager

Expected output: active (running). If it is not, start it with sudo systemctl enable --now docker and check the logs with journalctl -u docker -n 50.

Step 2 - Verifying the Compose plugin installation

With the plugin installed, the command is docker compose, not docker-compose. Check the version to confirm everything matches.

docker compose version

Expected output should look like Docker Compose version v2.29.7 or a newer v2 release. If you see docker-compose version 1.29.2, you have the legacy standalone binary in your PATH, and it is shadowing the plugin. Remove it before going further:

sudo rm /usr/local/bin/docker-compose
hash -r
docker compose version

The hash -r clears the shell's command lookup cache, which otherwise keeps pointing at the deleted binary. This is the classic trap: people install the plugin, run docker-compose out of habit, and get an old v1 prompt. Train your muscle memory now. The hyphen is gone.

Step 3 - Testing Compose with a real stack

Version output proves the binary exists, but it does not prove Compose can talk to the daemon. Run a minimal two-service stack to exercise the full path. Create a project directory and a compose.yaml file.

mkdir -p ~/compose-test && cd ~/compose-test
cat > compose.yaml <<'EOF'
services:
  web:
    image: nginx:alpine
    ports:
      - "8080:80"
  redis:
    image: redis:alpine
EOF

This stack declares an Nginx container publishing port 8080 and a Redis container with no published ports. Start it in detached mode.

docker compose up -d

You should see Container compose-test-web-1 Started and Container compose-test-redis-1 Started. Verify both containers are running and check the exposed port.

docker compose ps
curl -I http://localhost:8080

The curl should return HTTP/1.1 200 OK. If the port is closed, check whether a firewall is blocking it. On Ubuntu, sudo ufw status shows the rules; allow the port with sudo ufw allow 8080/tcp if needed. Now tear the stack down so it does not linger.

docker compose down

This removes the containers but keeps the project directory and the compose.yaml file. You can reuse the directory for real projects.

Step 4 - Running Compose without sudo (permission fix)

Every docker command prefixing with sudo gets old fast, and it causes file permission mismatches in bind mounts. Fix it by adding your user to the docker group. This is the standard approach on a single-user VPS where you trust the only account that logs in.

sudo usermod -aG docker $USER
newgrp docker
docker compose version

The newgrp docker command applies the group change to the current session without logging out. Test that the daemon accepts your user directly.

docker info | grep -i "permissions\|rootless"

If the command returns without a permission error, your user can talk to the daemon. One security note: membership in the docker group is equivalent to root access, because the group can mount host directories and run privileged containers. Only add accounts you trust completely. If you want stronger isolation, look into rootless Docker, but that is a separate setup with its own trade-offs and it does not play well with all Compose features yet.

Troubleshooting common Compose install problems

Two failures cover most support tickets. Here is how to diagnose and fix both.

"docker: command not found" after installing the plugin

You installed docker-compose-plugin by itself on a host that never had Docker Engine. The plugin is just a CLI extension; it needs the docker binary and a running daemon. Install the full set from Step 1, then recheck.

sudo apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin
sudo systemctl enable --now docker
docker compose version

"permission denied while trying to connect to the Docker daemon socket"

Your user is not in the docker group, or the group change has not applied to the current shell. Run the usermod command from Step 4, then either log out and back in or use newgrp docker. Check group membership with groups.

"no configuration file provided: not found"

You ran docker compose up outside the project directory. Compose looks for compose.yaml or docker-compose.yml in the current directory. Run cd into the project folder first, or point Compose at the file explicitly:

docker compose -f ~/compose-test/compose.yaml up -d

If the daemon itself is unhealthy, the fastest diagnostic is journalctl -u docker -n 50 --no-pager, which shows why the service failed to start. Most commonly it is a corrupted daemon.json or a port conflict on the API socket.

FAQ

Related articles

• Install Docker on an Ubuntu VPS
• Run multiple sites on one VPS with Docker and Nginx proxy
• Manage Docker containers with Portainer on a VPS