BuildWithMatija
  1. Home
  3. Blog
  5. Docker
  7. Update Docker to Latest Version on Ubuntu

Update Docker to Latest Version on Ubuntu

Remove outdated packages, add Docker's official repo, and fix 'client version too old' errors

16th August 2025·Updated on:3rd June 2026··
Docker
Update Docker to Latest Version on Ubuntu

🐳 Docker & DevOps Implementation Guides

Complete Docker guides with optimization techniques, deployment strategies, and automation prompts to streamline your containerization workflow.

No spam. Unsubscribe anytime.

Related Posts:

  • •Docker Compose env_file: When to Use vs environment Variables
  • •Docker Volume is in Use Error? 4 Proven Solutions
  • •Migrating Docker Containers Between VPS Servers Without Data Loss
📄View markdown version
0

About the author

Matija Žiberna

Matija Žiberna

Full-stack developer, co-founder

AboutResume

Self-taught full-stack developer sharing lessons from building software and startups.

I'm Matija Žiberna, a self-taught full-stack developer and co-founder passionate about building products, writing clean code, and figuring out how to turn ideas into businesses. I write about web development with Next.js, lessons from entrepreneurship, and the journey of learning by doing. My goal is to provide value through code—whether it's through tools, content, or real-world software.

You might be interested in

Docker Compose env_file: When to Use vs environment Variables
Docker Compose env_file: When to Use vs environment Variables

13th May 2025

Docker Volume is in Use Error? 4 Proven Solutions
Docker Volume is in Use Error? 4 Proven Solutions

13th May 2025

Migrating Docker Containers Between VPS Servers Without Data Loss
Migrating Docker Containers Between VPS Servers Without Data Loss

18th October 2025

Contents

  • 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
  • 3. Add Docker's Official Repository
  • 4. Install the Latest Docker Engine
  • 5. Path B — Already on the Official Repo
  • 6. Verify the Upgrade
  • 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`
  • Conclusion
On this page:
  • 1. Check What You Have Installed
  • 1a. Why You Can't Just Run `apt upgrade docker-ce`
  • 2. Path A — Migrate from Ubuntu Packages
  • 3. Add Docker's Official Repository
  • 4. Install the Latest Docker Engine
Build with Matija logo

Build with Matija

Modern websites, content systems, and AI workflows built for long-term growth.

Services

  • Headless CMS Websites
  • Next.js & Headless CMS Advisory
  • AI Systems & Automation
  • Website & Content Audit

Resources

  • Case Studies
  • How I Work
  • Blog
  • CMS Hub
  • E-commerce Hub
  • Dashboard

Headless CMS

  • Payload CMS Developer
  • CMS Migration
  • Multi-Tenant CMS
  • Payload vs Sanity
  • Payload vs WordPress
  • Payload vs Contentful

Get in Touch

Ready to modernize your stack? Let's talk about what you're building.

Book a discovery callContact me →
© 2026Build with Matija•All rights reserved•Privacy Policy•Terms of Service
BuildWithMatija
Get In Touch

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 situationJump to
I have docker.io from Ubuntu's default reposPath A — Migrate and install
I already have docker-ce installedPath B — Upgrade only
I'm seeing "client version too old/new" errorsTroubleshooting

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.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 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. 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:

code
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:

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
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:

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.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:

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 — 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 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.sh is a known example using API 1.41)
  • Docker-in-Docker setups where the outer image is newer than the inner
  • Running apt upgrade docker-ce without upgrading docker-ce-cli 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 (e.g., docker:29 instead of docker:24).

"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 — 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:

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