Linux

How to Safely Upgrade Docker Engine on Ubuntu and RHEL Without Losing Containers

Aseem Kishore
14 min read

The Back Room Tech is reader-supported. We may earn a commission when you buy through links on our site. Learn more.

A Docker Engine package upgrade normally leaves containers, images, volumes, and networks in the data root (/var/lib/docker by default). Services can still go down. The upgrade also can’t recover application data lost or changed during a failed deployment. Record the current state, back up data, upgrade, and check each workload. This guide also includes a package rollback procedure to rehearse on a matching test host; it’s a rehearsal procedure, not a verified, tested guarantee for your production environment.

These commands are intended for existing Docker Engine installations on Ubuntu 22.04, Ubuntu 24.04, and RHEL 9, based on Docker’s official Ubuntu and RHEL installation guides. Not every command here has been validated against every release and repository combination, so confirm behavior on a matching test host before you rely on it in production. Your repository controls which package versions you can install.

What Is Docker Engine?

Docker Engine runs containers through the Docker daemon (dockerd) and its container runtime. An upgrade may change docker-ce, docker-ce-cli, containerd.io, docker-buildx-plugin, and docker-compose-plugin. Docker’s Ubuntu and RHEL guides say uninstalling Engine doesn’t automatically remove data under /var/lib/docker. That includes stored images, containers, volumes, and networks. The guides don’t promise uptime during a package change, so book a maintenance window.

Prerequisites

  • An existing Docker Engine host running Ubuntu 22.04, Ubuntu 24.04, or RHEL 9.
  • SSH access with sudo, plus access to Docker’s configured package repository.
  • Enough free space for downloads and backups on both the Docker data filesystem and the backup destination.
  • An off-host backup destination, such as a NAS drive, with space for application data.
  • The location of each Compose file, environment file, bind mount, and application health check.
  • A maintenance window that allows for a daemon or container restart.
  • A matching test VM if you plan to rely on package rollback.

Docker’s supplied documentation confirms RHEL 9. Check repository behavior separately on Rocky Linux 9 or AlmaLinux 9 before using these RHEL package steps.

Step-by-Step Guide: How to Safely Upgrade Docker Engine on Ubuntu and RHEL Without Losing Containers

Step 1: Confirm the host and Docker data location

Run these commands on the server you intend to upgrade:

cat /etc/os-release
docker context ls
docker info --format 'Docker root: {{.DockerRootDir}}'
docker version
df -h /var/lib/docker

Expected result: the OS shows one of the listed versions, and the active Docker context points to the right daemon. docker version should show both Client and Server details. If DockerRootDir differs from /var/lib/docker, use that path for storage checks and snapshots. If the Server section fails, fix the connection before you continue.

OS release, active Docker context, Docker root directory, and Client and Server versions on the target host

Step 2: Save package and workload inventory

Create a local change record. It may contain container names, mount paths, and registry names. Store it with your usual operational records.

CHANGE_DIR="$HOME/docker-upgrade-$(date +%Y%m%d-%H%M%S)"
mkdir -p "$CHANGE_DIR"

docker version > "$CHANGE_DIR/docker-version.before.txt"
docker info > "$CHANGE_DIR/docker-info.before.txt"
docker ps -a --no-trunc > "$CHANGE_DIR/containers.before.txt"
docker volume ls > "$CHANGE_DIR/volumes.before.txt"
docker network ls > "$CHANGE_DIR/networks.before.txt"
docker compose ls > "$CHANGE_DIR/compose.before.txt"
docker inspect $(docker ps -aq) > "$CHANGE_DIR/container-inspect.before.json"

If the host has no containers, omit the last command. For package records, run the block for your OS:

Ubuntu

dpkg-query -W docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin > "$CHANGE_DIR/packages.before.txt"
apt-cache policy docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin > "$CHANGE_DIR/package-policy.before.txt"

RHEL 9

rpm -q docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin > "$CHANGE_DIR/packages.before.txt"
dnf list installed docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin > "$CHANGE_DIR/package-list.before.txt"

Expected result: the change directory holds package versions and lists of containers, volumes, networks, and Compose projects. Check for services you might forget. Record each container’s restart policy, too:

docker ps -aq | xargs -r docker inspect --format '{{.Name}}: {{.HostConfig.RestartPolicy.Name}}'
Saved package versions, container inventory, volumes, networks, and restart policies before the upgrade

Step 3: Back up configuration and application data

Copy /etc/docker/daemon.json if it exists. Copy any systemd override under /etc/systemd/system/docker.service.d/, too. Save each workload’s Compose and environment files. For a project in /srv/myapp, use:

sudo tar -C / -czf "$CHANGE_DIR/docker-config.tgz" etc/docker etc/systemd/system/docker.service.d
sudo tar -C / -czf "$CHANGE_DIR/myapp-files.tgz" srv/myapp

Change the paths to match your host. If an optional configuration directory is missing, remove it from the command. tar will fail if you leave it in.

Back up named volumes and bind-mounted data, too. For a named volume whose application has stopped cleanly, this example writes an archive to the change directory. Replace myapp_data with a name from docker volume ls:

VOLUME_NAME="myapp_data"
docker run --rm \
  -v "$VOLUME_NAME:/source:ro" \
  -v "$CHANGE_DIR:/backup" \
  busybox tar -C /source -czf "/backup/$VOLUME_NAME.tgz" .

-v mounts the volume in the helper container. :ro makes that mount read-only. The busybox image must be on the host, or Docker must be able to pull it. Check the archive before you move on:

ls -lh "$CHANGE_DIR"
tar -tzf "$CHANGE_DIR/$VOLUME_NAME.tgz"

For databases, take an application-native backup or pause writes before archiving a volume. A tar copy made while files change may not restore cleanly. Copy completed backups off the host. A VM snapshot gives you another recovery point for the whole host, but it can’t replace a checked database backup.

Step 4: Review the target release and downtime plan

Read the Docker Engine release notes for your target version. Check changes to your storage driver, networking, registry access, and API clients.

Docker’s live-restore feature can keep containers running through some daemon restarts, but current Docker documentation limits that support to patch-level restarts within the same YY.MM release line, not a major-version Engine upgrade like the one in this guide.

It can’t promise uninterrupted service through a package upgrade, a container runtime change, a daemon-option change, a storage-driver change, a networking change, or a host reboot. If you use it, read Docker’s current live-restore guidance for its exact scope before you count on it. Then test the same package transaction on a matching host. Plan for an interruption unless you’ve measured otherwise.

Write down a check for each service: a local health endpoint, a login, an application database query, or a request from another client. A UPS can cover an unrelated power failure during the maintenance window. It can’t make the package change risk-free.

Step 5: List available versions and confirm the rollback candidate

Ubuntu

sudo apt update
apt-cache madison docker-ce
apt-cache madison docker-ce-cli

RHEL 9

sudo dnf makecache
dnf list --showduplicates docker-ce docker-ce-cli

Expected result: the repository lists your target version. Compare it with packages.before.txt. Check that the previous version and its required dependencies are still in the repository or your package archive. If you can’t get those packages, you don’t have a package rollback path yet.

Available Docker Engine package versions alongside the previously installed versions

Step 6: Upgrade on Ubuntu

This command installs the newest versions your configured Docker repository offers, which may not be the newest Engine release in Docker’s release notes:

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

For a specific Engine version, copy the full string from apt-cache madison docker-ce. Set it below, then review the proposed transaction before you accept it:

VERSION_STRING="PASTE_VERSION_FROM_APT_CACHE_MADISON"
sudo apt install docker-ce="$VERSION_STRING" docker-ce-cli="$VERSION_STRING" containerd.io docker-buildx-plugin docker-compose-plugin

This pins only the two Engine packages, which need an available, matching version string. apt picks versions for containerd.io, Buildx and Compose, so the result isn’t a fully pinned set. If you need exact versions for those too, pin each one from its own apt-cache madison output. Read the plan, especially if it proposes removals or mixes package generations you didn’t expect.

After you verify the upgrade, hold the installed package set if you need to block an unattended version change:

sudo apt-mark hold docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
apt-mark showhold

Release the hold before a later planned upgrade:

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

Expected result: apt finishes without package errors, and apt-mark showhold lists the packages you held.

Step 7: Upgrade on RHEL 9

This command installs the newest versions of these packages that your configured Docker repository offers (not necessarily the newest Engine release in Docker’s release notes), provided that repository actually serves docker-ce, docker-ce-cli, containerd.io, docker-buildx-plugin, and docker-compose-plugin. Behavior can vary depending on how your repository is configured, so review DNF’s planned transaction before you confirm it:

sudo dnf upgrade docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

For a specific version, copy the full version and release from dnf list --showduplicates. Use the matching package names and review DNF’s plan before you approve it:

CE_VERSION="PASTE_VERSION_AND_RELEASE_FROM_DNF"
sudo dnf install "docker-ce-$CE_VERSION" "docker-ce-cli-$CE_VERSION" containerd.io docker-buildx-plugin docker-compose-plugin

As with apt, this pins only the Engine packages; DNF resolves containerd.io, Buildx and Compose from what the repository offers. Pin those from dnf list --showduplicates too if you need an exact set, and stop if the transaction fails dependency resolution or mixes package generations unexpectedly.

If the DNF versionlock plugin is available, lock the verified package set after the change:

sudo dnf install 'dnf-command(versionlock)'
sudo dnf versionlock add docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
sudo dnf versionlock list

Remove the locks before a later planned update:

sudo dnf versionlock delete docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

Expected result: DNF reports a completed transaction, and dnf versionlock list shows the locked versions. Check plugin availability and package names against your RHEL repository setup before the maintenance window.

Step 8: Verify the daemon and every important workload

Run these checks after either upgrade:

sudo systemctl is-active docker
docker version
docker info --format 'Docker root: {{.DockerRootDir}}'
docker ps -a
docker volume ls
docker network ls
docker compose ls
docker ps -aq | xargs -r docker inspect --format '{{.Name}}: {{.State.Status}}; restart={{.HostConfig.RestartPolicy.Name}}'

Expected result: systemctl prints active, the Server shows the target version, and Docker reports the same data root. Your expected containers, volumes, networks, and Compose projects should still appear. A listed container doesn’t prove its application works. Run the Step 4 check for each important service. Where it matters, check from outside the host too.

For a Compose project, go to its actual directory and check status:

cd /srv/myapp
docker compose ps

If the project lives elsewhere, use that directory. Check logs for any service that has stopped, keeps restarting, or reports unhealthy:

docker compose logs --tail=100
Active Docker service, target Server version, container states, restart policies, and Compose service status after the upgrade

Step 9: Rehearse and document package rollback

Rehearse rollback on a matching test host before you count on it in production. Use the versions in packages.before.txt. Check that they’re available, and back up any data changed since the upgrade.

On Ubuntu, release package holds first. Then replace the sample values with that host’s exact previous versions:

sudo apt-mark unhold docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
OLD_CE="PASTE_PREVIOUS_DOCKER_CE_VERSION"
OLD_CONTAINERD="PASTE_PREVIOUS_CONTAINERD_IO_VERSION"
OLD_BUILDX="PASTE_PREVIOUS_BUILDX_PLUGIN_VERSION"
OLD_COMPOSE="PASTE_PREVIOUS_COMPOSE_PLUGIN_VERSION"
sudo apt install --allow-downgrades \
  docker-ce="$OLD_CE" \
  docker-ce-cli="$OLD_CE" \
  containerd.io="$OLD_CONTAINERD" \
  docker-buildx-plugin="$OLD_BUILDX" \
  docker-compose-plugin="$OLD_COMPOSE"

On RHEL 9, remove version locks. Use the exact previous package versions and releases you saved before the upgrade:

sudo dnf versionlock delete docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
OLD_CE="PASTE_PREVIOUS_CE_VERSION_AND_RELEASE"
OLD_CONTAINERD="PASTE_PREVIOUS_CONTAINERD_VERSION_AND_RELEASE"
OLD_BUILDX="PASTE_PREVIOUS_BUILDX_VERSION_AND_RELEASE"
OLD_COMPOSE="PASTE_PREVIOUS_COMPOSE_VERSION_AND_RELEASE"
sudo dnf install \
  "docker-ce-$OLD_CE" \
  "docker-ce-cli-$OLD_CE" \
  "containerd.io-$OLD_CONTAINERD" \
  "docker-buildx-plugin-$OLD_BUILDX" \
  "docker-compose-plugin-$OLD_COMPOSE"

Review the package transaction before you confirm it. Stop if old packages are missing, dependencies conflict, or DNF or apt proposes unexpected removals. Use your documented host recovery plan instead. Repeat Step 8 after a downgrade. Record the test host, date, versions, commands, and application check results. Until you do, rollback is a procedure to rehearse, not a tested guarantee.

A package rollback restores package versions. It does not undo database writes, volume schema changes, deleted bind-mounted files, or a failed application migration. Those need an application-data restore.

Configuration

SettingWhat to record or decide
/etc/docker/daemon.jsonBack up the file. Check custom data-root, logging, and network settings before changing packages.
Restart policyRecord it for each important container. A stopped container may need an explicit start after the transaction.
Compose files and environment filesKeep the exact files used for each project, including any external configuration they reference.
Docker context and DOCKER_HOSTCheck that post-upgrade commands reach the same daemon as pre-upgrade commands.
Live-restoreCovers patch-level daemon restarts within a release line, not major-version Engine upgrades like this one. Read current Docker guidance and test your exact upgrade path before relying on it.

Compact change checklist

  • Before: record package and workload state; read release notes; take and check off-host backups; confirm old package availability; schedule application checks.
  • After: confirm the daemon and target version; compare containers, volumes, networks, and restart policies; check every application; record results and downtime.

Tips and Troubleshooting

Package manager reports a containerd or Docker package conflict

Distribution packages such as docker.io, containerd, or runc can conflict with Docker’s official packages. Check what’s installed and read the full proposed transaction before you remove anything:

# Ubuntu
dpkg-query -W docker.io containerd runc docker-ce containerd.io
# RHEL 9
rpm -q docker docker-client containerd runc podman docker-ce containerd.io

A “not installed” result for some names is normal. Follow the conflicting-package steps in Docker’s Ubuntu or RHEL guide for packages on your host. Check whether another service uses them before you approve a removal.

Docker fails to start after the upgrade

Check the service and recent logs, then validate the daemon configuration the systemd-managed service actually uses:

sudo systemctl status docker --no-pager
sudo journalctl -u docker -n 100 --no-pager
if [ -f /etc/docker/daemon.json ]; then
  sudo dockerd --validate --config-file=/etc/docker/daemon.json
else
  sudo dockerd --validate
fi

Pointing --validate at /etc/docker/daemon.json explicitly ensures you’re checking the same file systemd loads, rather than whatever default config dockerd would otherwise assume. If validation reports an error in that file, fix the reported setting or restore your saved configuration. Then start Docker again:

sudo systemctl restart docker
sudo systemctl is-active docker

Restarting Docker can interrupt workloads. Use the maintenance window, then check the applications again.

Containers appear missing or remain stopped

First check that you’re querying the same daemon and data root:

docker context ls
docker info --format 'Docker root: {{.DockerRootDir}}'
docker ps -a

Check whether DOCKER_HOST is set in your shell:

printenv DOCKER_HOST

If a known container is present but stopped, check its exit state and restart policy before you start it:

docker inspect --format '{{.State.Status}} {{.State.ExitCode}} {{.HostConfig.RestartPolicy.Name}}' CONTAINER_NAME
docker start CONTAINER_NAME

Replace CONTAINER_NAME with a name from docker ps -a. Then test the application as well as the container state.

Published ports or container networking stop working

Compare docker ps port mappings and docker network ls with your saved records. Check Docker’s log and the host firewall before you change rules:

docker ps
docker network ls
sudo journalctl -u docker -n 100 --no-pager

Docker’s installation guides describe firewall limits, including interactions with ufw, firewalld, and packet-filter rules. Use the relevant Docker firewall guidance for your host. Broad firewall resets during a remote session can make a bad afternoon worse.

Wrapping Up

You need a working application, saved package versions, and data you can restore. Docker keeps its data directory through a normal package upgrade, but that alone can’t tell you whether users can reach a service. Check the applications, and keep the backup until you’ve verified recovery.

StepActionApplies To
PrepareInventory, release review, and application-consistent backupBoth
ChangeUpgrade and optionally hold package versionsUbuntu or RHEL 9
VerifyCheck daemon, workloads, and applicationsBoth
RecoverRehearse package rollback; restore data when neededBoth