---
title: "Update Docker to Latest Version on Ubuntu"
slug: "update-docker-to-latest-ubuntu"
published: "2025-08-16"
updated: "2026-03-03"
validated: "2025-12-26"
categories:
  - "Docker"
tags:
  - "update docker ubuntu"
  - "upgrade docker ubuntu"
  - "ubuntu update docker"
  - "ubuntu upgrade docker"
  - "how to update docker"
  - "docker upgrade"
  - "docker engine update"
  - "latest docker version"
  - "docker-ce installation"
  - "install latest docker"
llm-intent: "reference"
audience-level: "intermediate"
framework-versions:
  - "ubuntu@24.04"
  - "docker@latest"
status: "stable"
llm-purpose: "Learn how to upgrade Docker to the latest version on Ubuntu by switching from default Ubuntu packages to Docker's official repository."
llm-prereqs:
  - "Access to docker"
  - "Access to ubuntu"
llm-outputs:
  - "Completed outcome: Learn how to upgrade Docker to the latest version on Ubuntu by switching from default Ubuntu packages to Docker's official repository."
---

**Summary Triples**
- (Old packages, should be removed using, sudo apt remove docker docker-engine docker.io containerd runc)
- (Docker data (images/containers/volumes), is preserved at, /var/lib/docker)
- (GPG key, is stored at, /etc/apt/keyrings/docker.gpg)
- (Apt source, must include, deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable)
- (Install command, installs, docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin)
- (Verification, can be done with, docker --version and docker run --rm hello-world)
- (Non-root Docker access, is enabled by, sudo usermod -aG docker <username> and new login session)

### {GOAL}
Learn how to upgrade Docker to the latest version on Ubuntu by switching from default Ubuntu packages to Docker's official repository.

### {PREREQS}
- Access to docker
- Access to ubuntu

### {STEPS}
1. Follow the detailed walkthrough in the article content below.

<!-- llm:goal="Learn how to upgrade Docker to the latest version on Ubuntu by switching from default Ubuntu packages to Docker's official repository." -->
<!-- llm:prereq="Access to docker" -->
<!-- llm:prereq="Access to ubuntu" -->
<!-- llm:output="Completed outcome: Learn how to upgrade Docker to the latest version on Ubuntu by switching from default Ubuntu packages to Docker's official repository." -->

# Update Docker to Latest Version on Ubuntu
> Update Docker to latest version on Ubuntu: remove old packages, add Docker's official repository, and install docker-ce with latest plugins and security updates.
Matija Žiberna · 2025-08-16

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](#2-path-a-migrate-from-ubuntu-packages) |
| I already have `docker-ce` installed | [Path B — Upgrade only](#5-path-b-already-on-the-official-repo) |
| I'm seeing "client version too old/new" errors | [Troubleshooting](#7-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.2.1 as of early 2026). You can always verify the current version at the [Docker Engine release notes](https://docs.docker.com/engine/release-notes/).

> [!NOTE]
> `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:

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

> [!TIP]
> 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](/blog/how-to-delete-docker-volumes-even-when-in-use).
---

## 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](#1a-why-you-cant-just-run-apt-upgrade-docker-ce) and [Troubleshooting](#7-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](https://docs.docker.com/engine/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.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"

```
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](/blog/how-to-fix-permission-denied-when-manipulating-files-in-docker-container).

---

## 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](/blog/difference-between-environment-and-env_file-in-docker-compose), [exposing containers with Cloudflare Tunnel](/blog/cloudflared-tunnel-expose-docker-no-nginx-open-ports), and [automating SSL certificate renewal with Certbot](/blog/how-to-set-up-automatic-ssl-certificate-renewal-with-certbot-in-docker-containers).
Matija

## LLM Response Snippet
```json
{
  "goal": "Learn how to upgrade Docker to the latest version on Ubuntu by switching from default Ubuntu packages to Docker's official repository.",
  "responses": [
    {
      "question": "What does the article \"How to Upgrade Docker to the Latest Version on Ubuntu\" cover?",
      "answer": "Learn how to upgrade Docker to the latest version on Ubuntu by switching from default Ubuntu packages to Docker's official repository."
    }
  ]
}
```