Update Docker to Latest Version on Ubuntu
Remove outdated packages, add Docker's official repo, and fix 'client version too old' errors
🐳 Docker & DevOps Implementation Guides
Complete Docker guides with optimization techniques, deployment strategies, and automation prompts to streamline your containerization workflow.
Related Posts:
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-cefrom 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:
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.2.1 as of early 2026). You can always verify the current version at the Docker Engine release notes.
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 daemondocker-ce-cli— the CLI clientcontainerd.io— the container runtimedocker-buildx-plugin— extended build supportdocker-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. Starting with Docker 29, the daemon requires a minimum API version of 1.44 (Docker 25.0+). Any client tool still sending API 1.41 or older will get this error:
Error response from daemon: client version 1.41 is too old. Minimum supported API version is 1.44, please upgrade your client to a newer version.
This trips up GitLab Runner, CI pipelines, and any script that hardcodes an older API version — not because you did something wrong with apt, but because the CLI and daemon 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:
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:
sudo apt update
sudo apt install ca-certificates curl
Add Docker's GPG key:
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:
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
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 — jammy on 22.04, noble on 24.04. The same commands work on both 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:
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:
# List available versions
apt list --all-versions docker-ce
# Install a specific version (example)
VERSION_STRING=5:29.2.1-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:
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:
docker --version docker compose version docker buildx version
Expected output will show Docker version 29.x.x — cross-check against the release notes to confirm you're on the latest stable build.
7. Troubleshooting
"client version X is too old"
Error response from daemon: client version 1.41 is too old. Minimum supported API version is 1.44, please upgrade your client to a newer version.
This error means your CLI (or a tool making Docker API calls) is older than Docker 29's minimum supported API version. Starting with Docker 29, the daemon requires API version 1.44 as a minimum — clients that are Docker 24.x era or older (API 1.43 and below) will be rejected.
Common triggers:
- CI tools that hardcode an older Docker API version (GitLab Runner's
clear-docker-cache.shis a known example using API 1.41) - Docker-in-Docker setups where the outer image is newer than the inner
- Running
apt upgrade docker-cewithout upgradingdocker-ce-cliat the same time
Fix: upgrade the CLI on the machine running the Docker commands:
sudo apt update
sudo apt install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
Then verify both sides match:
docker version
For CI or Docker-in-Docker scenarios, update the base image tag in your pipeline (e.g., docker:29 instead of docker:24).
"client version X is too new"
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:
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:
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:
docker compose version # correct V2 syntax
Add an alias to avoid rewriting scripts:
alias docker-compose='docker compose'
Permission denied on docker.sock
If Docker commands stop working for your user after an upgrade:
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:
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 — the current stable line — runs API version 1.52 and enforces a minimum of 1.44, so any client or tool from the Docker 24.x era will need to be updated.
With the official repo configured, future upgrades are two commands:
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
