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.
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}}'
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.
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
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
| Setting | What to record or decide |
|---|---|
/etc/docker/daemon.json | Back up the file. Check custom data-root, logging, and network settings before changing packages. |
| Restart policy | Record it for each important container. A stopped container may need an explicit start after the transaction. |
| Compose files and environment files | Keep the exact files used for each project, including any external configuration they reference. |
Docker context and DOCKER_HOST | Check that post-upgrade commands reach the same daemon as pre-upgrade commands. |
| Live-restore | Covers 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.
| Step | Action | Applies To |
|---|---|---|
| Prepare | Inventory, release review, and application-consistent backup | Both |
| Change | Upgrade and optionally hold package versions | Ubuntu or RHEL 9 |
| Verify | Check daemon, workloads, and applications | Both |
| Recover | Rehearse package rollback; restore data when needed | Both |