Update Docker to Latest Version on Ubuntu

Updating Docker on Ubuntu has two different starting points, and most guides only cover one:

You're on Ubuntu's bundled docker.io — you need to migrate to Docker's official repo first, then install the latest engine.
You already have docker-ce from Docker's official repo — you just need two commands to upgrade.

This guide covers both paths, plus a troubleshooting section for the version mismatch errors that show up after upgrades.

Your situation	Jump to
I have `docker.io` from Ubuntu's default repos	Path A — Migrate and install
I already have `docker-ce` installed	Path B — Upgrade only
I'm seeing "client version too old/new" errors	Troubleshooting

1. Check What You Have Installed

Before doing anything, check which Docker you're running:

bash

docker version
which docker

If which docker returns /usr/bin/docker and the version is something like 24.0.x, you're likely on Ubuntu's bundled package. If it shows docker-ce in the output of docker version, you're already on the official repo.

The latest stable Docker Engine release is 29.x (29.5.3 as of June 2026). Docker's official Ubuntu repository supports Ubuntu 26.04 LTS (resolute), Ubuntu 24.04 LTS (noble), and Ubuntu 22.04 LTS (jammy). You can always verify the current version at the Docker Engine release notes.

June 2026 update: Ubuntu 26.04 LTS "Resolute Raccoon" is now the latest Ubuntu LTS release. The commands below work on supported Ubuntu LTS releases as long as Docker's official repository is used. docker update is not how you upgrade Docker Engine. It's a container resource command (docker container update) that adjusts CPU, memory, and restart policies for running containers. To upgrade the Engine itself, you use apt — which is what the rest of this guide covers.

1a. Why You Can't Just Run `apt upgrade docker-ce`

Docker Engine is split across five packages that must stay in sync:

docker-ce — the daemon
docker-ce-cli — the CLI client
containerd.io — the container runtime
docker-buildx-plugin — extended build support
docker-compose-plugin — Compose V2

If you only run sudo apt upgrade docker-ce, you can end up with a newer daemon alongside an older CLI. Docker 29.0 originally raised the minimum supported API version to 1.44, which caused older clients and CI tools to fail. Docker later lowered the Docker 29 minimum back to 1.40 in the 29.3 release line, but mismatched clients can still break after partial upgrades.

A common version mismatch looks like this:

code

Error response from daemon: client version X is too old. Minimum supported API version is Y, please upgrade your client to a newer version.

This trips up GitLab Runner, CI pipelines, Docker-in-Docker images, and any script that hardcodes an older API version — not because you did something wrong with apt, but because the CLI, daemon, or API client got out of sync.

Always upgrade all five packages together. Both Path A and Path B in this guide use the full install command, which is also what Docker's official documentation recommends.

2. Path A — Migrate from Ubuntu Packages

Remove conflicting packages

Ubuntu ships its own Docker packages under different names. Remove them before installing the official ones — they will conflict:

bash

sudo apt remove docker.io docker-compose docker-compose-v2 docker-doc podman-docker containerd runc

This does not delete your images, containers, or volumes — they're stored in /var/lib/docker and survive the package removal.

If you want to clean up volumes that might be stuck in use, see the guide on deleting Docker volumes safely.

3. Add Docker's Official Repository

Docker's current setup uses an .asc key file and a DEB822-format sources file — this is different from older guides that used gpg --dearmor and a one-line .list file. Use the commands below.

Install prerequisites:

bash

sudo apt update
sudo apt install ca-certificates curl

Add Docker's GPG key:

bash

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 Docker apt repository:

bash

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
sudo apt update

The $UBUNTU_CODENAME:-$VERSION_CODENAME expression resolves automatically to the correct codename for your Ubuntu version — resolute on 26.04, noble on 24.04, and jammy on 22.04. The same commands work on supported Ubuntu LTS releases without any changes. On Ubuntu derivatives like Linux Mint, UBUNTU_CODENAME ensures the correct Ubuntu base repo is used rather than the derivative's own codename.

4. Install the Latest Docker Engine

Install Docker Engine, CLI, and all plugins in one command:

bash

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

If you want to pin a specific version rather than always pulling the latest:

bash

# List available versions
apt list --all-versions docker-ce

# Install a specific version (example)
VERSION_STRING=5:29.5.3-1~ubuntu.24.04~noble
sudo apt install docker-ce=$VERSION_STRING docker-ce-cli=$VERSION_STRING containerd.io docker-buildx-plugin docker-compose-plugin

Only copy the exact version string after checking apt list --all-versions docker-ce, because the suffix changes by Ubuntu version — for example, Ubuntu 26.04 packages use ~ubuntu.26.04~resolute.

5. Path B — Already on the Official Repo

If you already have docker-ce installed from Docker's official repository, upgrading is straightforward. You don't need to touch the repo configuration — just update and reinstall:

bash

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

Use apt install rather than apt upgrade docker-ce alone — this ensures all five components move to the same version together. This matches Docker's official upgrade guidance. Upgrading only docker-ce while leaving docker-ce-cli behind is the most common cause of the client version X is too old error (see Section 1a and Troubleshooting for details).

6. Verify the Upgrade

Check all three components to confirm everything is on the same version:

bash

docker --version
docker compose version
docker buildx version

Expected output will show `Docker version 29.x.x` — for example, `29.5.3` at the time of this June 2026 refresh. Cross-check against the release notes to confirm you're on the latest stable build.

7. Troubleshooting

"client version X is too old"

code

Error response from daemon: client version X is too old. Minimum supported API version is Y, please upgrade your client to a newer version.

This error means your CLI, CI job, Docker-in-Docker image, or other tool making Docker API calls is older than the daemon will accept. Docker 29.0 originally raised the minimum to API 1.44, but Docker later lowered the Docker 29 minimum back to 1.40 in the 29.3 release line. If you still see this error, treat it as a version mismatch and upgrade the full Docker package bundle.

Common triggers:

CI tools that hardcode an older Docker API version
Docker-in-Docker setups where the outer image is newer than the inner image
Running apt upgrade docker-ce without upgrading docker-ce-cli, Buildx, Compose, and containerd at the same time

Fix: upgrade the CLI on the machine running the Docker commands:

bash

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

Then verify both sides match:

bash

docker version

For CI or Docker-in-Docker scenarios, update the base image tag in your pipeline so the client image matches the daemon closely enough for Docker's supported API range.

"client version X is too new"

code

Error response from daemon: client version 1.47 is too new. Maximum supported API version is 1.43

Your CLI is newer than the daemon on the target host. The proper fix is to upgrade the daemon:

bash

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

If you can't upgrade the daemon right now, set the API version as a temporary workaround:

bash

export DOCKER_API_VERSION=1.43

Replace 1.43 with whatever the daemon reports as its maximum supported version in the error message.

"docker compose" not found after upgrade

Docker Compose V2 is installed as a plugin and uses a space: docker compose. The old standalone binary used a hyphen: docker-compose. If your scripts use the old syntax:

bash

docker compose version   # correct V2 syntax

Add an alias to avoid rewriting scripts:

bash

alias docker-compose='docker compose'

Permission denied on docker.sock

If Docker commands stop working for your user after an upgrade:

bash

sudo usermod -aG docker $USER
newgrp docker

Log out and back in (or reconnect via SSH) for the group change to persist across sessions. For a detailed breakdown of Docker permission errors including bind mounts and CI/CD scenarios, see the guide on fixing Docker permission denied errors.

8. (Optional) Run Docker Without `sudo`

By default, Docker commands require sudo. To run as your regular user:

bash

sudo usermod -aG docker $USER

Then log out and back in (or disconnect/reconnect if using SSH).

Conclusion

The two most important things to get right when upgrading Docker on Ubuntu: use Docker's official repo (not Ubuntu's bundled docker.io), and always upgrade all five components together to avoid version mismatch errors. Docker 29 is the current stable line, and Ubuntu 26.04 LTS is now the latest Ubuntu LTS release, so this guide uses Docker's official repository flow for 26.04, 24.04, and 22.04.

With the official repo configured, future upgrades are two commands:

bash

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

For next steps, see the guides on environment variables in Docker Compose, exposing containers with Cloudflare Tunnel, and automating SSL certificate renewal with Certbot. Matija

Updating Docker on Ubuntu has two different starting points, and most guides only cover one:

You're on Ubuntu's bundled docker.io — you need to migrate to Docker's official repo first, then install the latest engine.
You already have docker-ce from Docker's official repo — you just need two commands to upgrade.

This guide covers both paths, plus a troubleshooting section for the version mismatch errors that show up after upgrades.

Your situation	Jump to
I have `docker.io` from Ubuntu's default repos	Path A — Migrate and install
I already have `docker-ce` installed	Path B — Upgrade only
I'm seeing "client version too old/new" errors	Troubleshooting

1. Check What You Have Installed

Before doing anything, check which Docker you're running:

bash

docker version
which docker

1a. Why You Can't Just Run `apt upgrade docker-ce`

Docker Engine is split across five packages that must stay in sync:

docker-ce — the daemon
docker-ce-cli — the CLI client
containerd.io — the container runtime
docker-buildx-plugin — extended build support
docker-compose-plugin — Compose V2

A common version mismatch looks like this:

code

Error response from daemon: client version X is too old. Minimum supported API version is Y, please upgrade your client to a newer version.

Always upgrade all five packages together. Both Path A and Path B in this guide use the full install command, which is also what Docker's official documentation recommends.

2. Path A — Migrate from Ubuntu Packages

Remove conflicting packages

Ubuntu ships its own Docker packages under different names. Remove them before installing the official ones — they will conflict:

bash

sudo apt remove docker.io docker-compose docker-compose-v2 docker-doc podman-docker containerd runc

This does not delete your images, containers, or volumes — they're stored in /var/lib/docker and survive the package removal.

If you want to clean up volumes that might be stuck in use, see the guide on deleting Docker volumes safely.

3. Add Docker's Official Repository

Docker's current setup uses an .asc key file and a DEB822-format sources file — this is different from older guides that used gpg --dearmor and a one-line .list file. Use the commands below.

Install prerequisites:

bash

sudo apt update
sudo apt install ca-certificates curl

Add Docker's GPG key:

bash

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 Docker apt repository:

bash

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
sudo apt update

4. Install the Latest Docker Engine

Install Docker Engine, CLI, and all plugins in one command:

bash

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

If you want to pin a specific version rather than always pulling the latest:

bash

# List available versions
apt list --all-versions docker-ce

# Install a specific version (example)
VERSION_STRING=5:29.5.3-1~ubuntu.24.04~noble
sudo apt install docker-ce=$VERSION_STRING docker-ce-cli=$VERSION_STRING containerd.io docker-buildx-plugin docker-compose-plugin

5. Path B — Already on the Official Repo

If you already have docker-ce installed from Docker's official repository, upgrading is straightforward. You don't need to touch the repo configuration — just update and reinstall:

bash

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

6. Verify the Upgrade

Check all three components to confirm everything is on the same version:

bash

docker --version
docker compose version
docker buildx version

Expected output will show `Docker version 29.x.x` — for example, `29.5.3` at the time of this June 2026 refresh. Cross-check against the release notes to confirm you're on the latest stable build.

7. Troubleshooting

"client version X is too old"

code

Error response from daemon: client version X is too old. Minimum supported API version is Y, please upgrade your client to a newer version.

Common triggers:

CI tools that hardcode an older Docker API version
Docker-in-Docker setups where the outer image is newer than the inner image
Running apt upgrade docker-ce without upgrading docker-ce-cli, Buildx, Compose, and containerd at the same time

Fix: upgrade the CLI on the machine running the Docker commands:

bash

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

Then verify both sides match:

bash

docker version

For CI or Docker-in-Docker scenarios, update the base image tag in your pipeline so the client image matches the daemon closely enough for Docker's supported API range.

"client version X is too new"

code

Error response from daemon: client version 1.47 is too new. Maximum supported API version is 1.43

Your CLI is newer than the daemon on the target host. The proper fix is to upgrade the daemon:

bash

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

If you can't upgrade the daemon right now, set the API version as a temporary workaround:

bash

export DOCKER_API_VERSION=1.43

Replace 1.43 with whatever the daemon reports as its maximum supported version in the error message.

"docker compose" not found after upgrade

Docker Compose V2 is installed as a plugin and uses a space: docker compose. The old standalone binary used a hyphen: docker-compose. If your scripts use the old syntax:

bash

docker compose version   # correct V2 syntax

Add an alias to avoid rewriting scripts:

bash

alias docker-compose='docker compose'

Permission denied on docker.sock

If Docker commands stop working for your user after an upgrade:

bash

sudo usermod -aG docker $USER
newgrp docker

8. (Optional) Run Docker Without `sudo`

By default, Docker commands require sudo. To run as your regular user:

bash

sudo usermod -aG docker $USER

Then log out and back in (or disconnect/reconnect if using SSH).

Conclusion

With the official repo configured, future upgrades are two commands:

bash

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

For next steps, see the guides on environment variables in Docker Compose, exposing containers with Cloudflare Tunnel, and automating SSL certificate renewal with Certbot. Matija

Update Docker to Latest Version on Ubuntu

1. Check What You Have Installed

1a. Why You Can't Just Run `apt upgrade docker-ce`

2. Path A — Migrate from Ubuntu Packages

Remove conflicting packages

If you want to clean up volumes that might be stuck in use, see the guide on deleting Docker volumes safely.

3. Add Docker's Official Repository

4. Install the Latest Docker Engine

5. Path B — Already on the Official Repo

6. Verify the Upgrade

Expected output will show `Docker version 29.x.x` — for example, `29.5.3` at the time of this June 2026 refresh. Cross-check against the release notes to confirm you're on the latest stable build.

7. Troubleshooting

"client version X is too old"

"client version X is too new"

"docker compose" not found after upgrade

Permission denied on docker.sock

8. (Optional) Run Docker Without `sudo`

Then log out and back in (or disconnect/reconnect if using SSH).

Conclusion

🐳 Docker & DevOps Implementation Guides

Related Posts:

You might be interested in

1. Check What You Have Installed

1a. Why You Can't Just Run `apt upgrade docker-ce`

2. Path A — Migrate from Ubuntu Packages

Remove conflicting packages

If you want to clean up volumes that might be stuck in use, see the guide on deleting Docker volumes safely.

3. Add Docker's Official Repository

4. Install the Latest Docker Engine

5. Path B — Already on the Official Repo

6. Verify the Upgrade

Expected output will show `Docker version 29.x.x` — for example, `29.5.3` at the time of this June 2026 refresh. Cross-check against the release notes to confirm you're on the latest stable build.

7. Troubleshooting

"client version X is too old"

"client version X is too new"

"docker compose" not found after upgrade

Permission denied on docker.sock

8. (Optional) Run Docker Without `sudo`

Then log out and back in (or disconnect/reconnect if using SSH).

Conclusion

1. Check What You Have Installed

1a. Why You Can't Just Run apt upgrade docker-ce

2. Path A — Migrate from Ubuntu Packages

Remove conflicting packages

If you want to clean up volumes that might be stuck in use, see the guide on deleting Docker volumes safely.

3. Add Docker's Official Repository

4. Install the Latest Docker Engine

5. Path B — Already on the Official Repo

6. Verify the Upgrade

Expected output will show Docker version 29.x.x — for example, 29.5.3 at the time of this June 2026 refresh. Cross-check against the release notes to confirm you're on the latest stable build.

7. Troubleshooting

"client version X is too old"

"client version X is too new"

"docker compose" not found after upgrade

Permission denied on docker.sock

8. (Optional) Run Docker Without sudo

Then log out and back in (or disconnect/reconnect if using SSH).

Conclusion

🐳 Docker & DevOps Implementation Guides

Related Posts:

You might be interested in

1. Check What You Have Installed

1a. Why You Can't Just Run apt upgrade docker-ce

2. Path A — Migrate from Ubuntu Packages

Remove conflicting packages

If you want to clean up volumes that might be stuck in use, see the guide on deleting Docker volumes safely.

3. Add Docker's Official Repository

4. Install the Latest Docker Engine

5. Path B — Already on the Official Repo

6. Verify the Upgrade

Expected output will show Docker version 29.x.x — for example, 29.5.3 at the time of this June 2026 refresh. Cross-check against the release notes to confirm you're on the latest stable build.

7. Troubleshooting

"client version X is too old"

"client version X is too new"

"docker compose" not found after upgrade

Permission denied on docker.sock

8. (Optional) Run Docker Without sudo

Then log out and back in (or disconnect/reconnect if using SSH).

Conclusion

1a. Why You Can't Just Run `apt upgrade docker-ce`

Expected output will show `Docker version 29.x.x` — for example, `29.5.3` at the time of this June 2026 refresh. Cross-check against the release notes to confirm you're on the latest stable build.

8. (Optional) Run Docker Without `sudo`

1a. Why You Can't Just Run `apt upgrade docker-ce`

Expected output will show `Docker version 29.x.x` — for example, `29.5.3` at the time of this June 2026 refresh. Cross-check against the release notes to confirm you're on the latest stable build.

8. (Optional) Run Docker Without `sudo`