Ubuntu Server / do-release-upgrade / How to upgrade your Ubuntu release

Use sudo do-release-upgrade to move Ubuntu Server to the next operating system release. First fully update the current release, confirm a supported upgrade path and prepare a backup you can restore.

Package updates and release upgrades

do-release-upgrade transitions Ubuntu’s base packages and system configuration to the next release. This differs from apt update, which refreshes package lists, and apt upgrade, which updates packages within the current release. For routine package management, see the Ubuntu Server apt guide.

Long Term Support (LTS) releases upgrade sequentially to the next LTS. For example, moving from 22.04 LTS to 26.04 LTS requires going through 24.04 LTS and checking operation at each stage. Do not bulk-replace repository codenames to skip releases. Check supported paths and support periods in the Ubuntu release cycle.

A new LTS is not immediately offered to every existing server. LTS-to-LTS upgrades are generally enabled after the first point release; use the upgrade tool to check what is actually offered. For a release that has reached end of support, plan recovery or migration separately rather than assuming this procedure applies unchanged.

Prepare backups and recovery access

Schedule downtime and work with an account that has administrative privileges. Review the target Ubuntu release notes and your applications’ support requirements. A web server booting successfully does not establish that its PHP runtime, database and extensions work correctly.

• Backups: Save service data, databases, configuration under /etc, certificates and recovery secrets in a secure separate location. Use the database product’s consistency-aware backup method and verify restoration. A snapshot of a running virtual machine alone does not guarantee database consistency.
• Recovery access: Prepare and test a physical console, remote management console or cloud serial console that works if SSH (Secure Shell) disconnects. Even when upgrading over SSH, do not depend on SSH as your only recovery route.
• Cloud requirements: Check the provider’s image, kernel, boot method and management-agent support. Cloud servers do not universally prohibit in-place upgrades. If restoration is difficult or service compatibility needs advance testing, also consider building a new server and migrating the data.

These commands inspect the current release, free space and inodes, incomplete package states and held packages. They do not start an upgrade.

cat /etc/os-release
uname -r
df -h / /boot
df -i / /boot
sudo dpkg --audit
apt-mark showhold

Record VERSION_ID and resolve space shortages on / and /boot first. Space requirements depend on the installation and proposed changes. Investigate any issues reported by dpkg --audit, and understand package holds before changing them. Do not remove all holds just to get past the upgrade checks.

Update the current release and check the release policy

1. Refresh the current release’s package lists and apply all updates. These preparation commands are documented in the official Ubuntu Server release-upgrade procedure.

sudo apt update
sudo apt dist-upgrade -o APT::Get::Always-Include-Phased-Updates=true

dist-upgrade resolves dependencies using the configured repositories and may remove packages. Read the proposed changes and stop if unexpected important packages would be removed. The option includes phased updates; this command itself does not change the Ubuntu release. Ensure both commands succeed and no updates remain outstanding.

2. Check whether /run/reboot-required exists. Its presence means a reboot is required to finish the current updates.

if [ -f /run/reboot-required ]; then
    cat /run/reboot-required
fi

If a reboot is needed, run sudo reboot during the maintenance window, reconnect and check services before continuing. The absence of the file does not mean application testing is complete.

3. If do-release-upgrade is missing, install the package that provides it, then inspect the release notification policy.

sudo apt install ubuntu-release-upgrader-core
cat /etc/update-manager/release-upgrades

You can skip installation if the command is already available. To keep an LTS server on the LTS upgrade path, use Prompt=lts in the configuration file. Prompt=normal also considers interim releases; it does not allow skipping releases. If a change is needed, back up the existing file under a separate name and edit only the relevant entry with sudoedit /etc/update-manager/release-upgrades. See Ubuntu’s LTS and interim release policy guide for the distinction.

Check the target release and start the upgrade

First check whether a release upgrade is available. The -c option checks and exits without starting an upgrade; it does not test application compatibility.

sudo do-release-upgrade -c

If no target is offered, check the current version, supported path, Prompt policy, outstanding updates, network access and release availability. In the do-release-upgrade manual, -d checks for a development release and can also be used to evaluate a new LTS before its first point release. Do not add it indiscriminately on a production server to bypass a “no new release” message.

Once backups and recovery access are ready and the offered target matches your plan, start with the following command. Do not add automatic-approval options; remain available to answer prompts.

sudo do-release-upgrade

• Change summary: Review the target release, packages to remove or install, download size and required space. If the plan would remove a critical service or otherwise differs from your expectations, stop before approving it and investigate. Once package installation begins, do not kill the process or power off the server.
• Configuration prompts: Compare the existing file with the package maintainer’s version before choosing. Follow the actual prompt for viewing differences and keeping or replacing a file. Always keeping or always replacing every file can lose either existing service settings or essential changes for the new version.
• External repositories and access: Personal Package Archives (PPAs) and third-party repositories are disabled during the upgrade. If the tool announces a separate recovery SSH port, review firewall and cloud security rules according to that message and restrict access to administrators. Do not disable the whole firewall or leave unnecessary ports permanently open.

Review the list when asked about obsolete packages. When the completed upgrade requests a reboot, reboot during the maintenance window and keep console access until post-upgrade checks are complete.

Check the release and services after reboot

Reconnect and verify the target release and any failed services. Compare the kernel version with your pre-upgrade record or the target release’s package information, then refresh the package lists.

cat /etc/os-release
uname -r
systemctl --failed
sudo apt update
apt list --upgradable

Confirm that VERSION_ID matches the intended release and investigate each entry reported by systemctl --failed. Even with no failed units, test web responses, database reads and writes, scheduled jobs, monitoring and backups against actual service requirements. Test a fresh SSH session before closing the recovery console.

Reconfigure only the external repositories you need after confirming support for the new Ubuntu release and compatibility with installed packages. Do not enable all repositories using the old codename. Perform further cleanup only after services are stable, reviewing packages proposed for removal.

Handle errors and lost connections

Preserve the final error message and logs under /var/log/dist-upgrade/. Ubuntu’s upgrade bug-reporting guidance identifies these logs as useful evidence. List the directory first and read the available logs to narrow down the failing stage and package-related causes.

sudo ls -lah /var/log/dist-upgrade/
sudo less /var/log/dist-upgrade/main.log

If SSH disconnects, use the recovery console to inspect the existing upgrade process and its progress first. Do not restart the upgrade or delete APT lock files simply because the connection dropped. An interruption during package processing requires recovery based on the logs and the current package state.

There is no general single command to undo a release upgrade and return to the previous Ubuntu version. If restoration is needed, restore tested server and database backups from a consistent point in time or switch to your prepared previous server. Account for writes made since the backup. Restoring the Prompt configuration file alone does not restore an operating system that has already changed.