Plan a Safe Ubuntu Release Upgrade with do-release-upgrade

You will check whether this Ubuntu installation has a release upgrade available, review the command's mode choices, and start the upgrade with a deliberate recovery plan. The examples match do-release-upgrade 24.04.29 from the installed ubuntu-release-upgrader-core package. Allow at least thirty minutes for preparation, plus the time needed for the upgrade itself. A production host may need a longer maintenance window.

This command changes the operating system. Before step 1, arrange a tested backup or snapshot, confirm that you can recover the machine if it does not boot, and tell anyone who depends on its services. For a remote machine, keep an out-of-band console or another recovery route available. An SSH session alone is not a rollback plan.

1. Confirm the installed command

Check the executable, package version and built-in syntax as an ordinary read-only user:

$ command -v do-release-upgrade
/usr/bin/do-release-upgrade
$ dpkg-query -W -f='${Package} ${Version}\n' ubuntu-release-upgrader-core
ubuntu-release-upgrader-core 1:24.04.29
$ do-release-upgrade --version
do-release-upgrade: version 24.04.29

The version matters. The installed manual describes the behaviour on this machine; another Ubuntu release can ship a different upgrader and different release policy. Read do-release-upgrade --help if you are working on another host instead of copying this option set blindly.

Checkpoint: stop if command -v finds an unexpected path or the package query fails. Do not download a replacement script merely because the local command is not available.

2. Check for an available release without starting an upgrade

Use --check-dist-upgrade-only, also written -c. The manual says this checks only whether a new distribution release is available and reports the result through the exit code:

$ do-release-upgrade --check-dist-upgrade-only
Checking for a new Ubuntu release
$ status=$?
$ printf 'check status: %s\n' "$status"
check status: 0

The text and status depend on the host's release configuration and what Ubuntu is offering. On this machine at the time of writing, the check printed There is no development version of an LTS available. and returned status 1. That is a report from this host, not a universal failure message.

Capture the status immediately. A later command changes $?. In a script, branch on the result and log the command output so an operator can see which release policy was checked. A non-zero status is a reason to investigate the output and current release configuration, not a reason to add --devel-release automatically.

3. Check the release policy before considering development code

The --devel-release or -d option asks for the development release when you are using the latest supported release. Development releases are not a normal production upgrade path. They can introduce unfinished changes and may not be available for the release policy configured on the machine.

Do not use -d to force progress after an ordinary check says that no upgrade is available. First establish that you deliberately want a development release, have a separate test or recovery plan, and have an outage window. If you only want the next supported release, leave -d out.

4. Prepare the machine and the maintenance window

Before the state-changing command, record the current release and the services that must be checked afterwards:

$ . /etc/os-release
$ printf 'release: %s %s\n' "$ID" "$VERSION_ID"
release: ubuntu 24.04
$ systemctl --failed --no-legend
$ systemctl list-units --type=service --state=running --no-legend

The service list is a record for your own change plan. The upgrader can disable or replace packages, alter configuration prompts, and require a reboot. Keep a copy of important configuration and data outside the machine. Make sure there is enough free space for downloaded packages and temporary upgrade data, and close unrelated package-management work before proceeding.

For a remote server, use a persistent terminal such as tmux or screen if available, but do not mistake that for protection from a network, power or boot failure. Prefer the provider's console for a critical host. Do not reboot or terminate the process because the terminal appears quiet; consult the upgrader's prompt or console first.

5. Start the supported upgrade deliberately

Read the proposed changes at each prompt. The normal command is:

$ sudo do-release-upgrade

Elevated privileges are required for the operating-system changes. The command is designed for command-line or remote upgrades, including machines without a graphical environment. Follow its prompts and keep the terminal open until it finishes or explicitly asks for a reboot.

Do not use --allow-third-party casually. The installed manual describes it as trying the upgrade with third-party mirrors and repositories enabled instead of commenting them out. Third-party packages and repositories are a common source of conflicts. Use this option only when you have reviewed each repository, its signing trust and its compatibility with the target release, and you accept that the upgrade may depend on it.

The --mode=server and --mode=desktop forms select the special mode described by the manual. Use the mode that matches the machine when you have a reason to select it; do not treat it as a release selector. --frontend=FRONTEND selects a frontend, but the manpage does not define a universal list of frontend names. Do not invent one in automation.

6. Verify the result after the reboot

After the upgrader completes and you have rebooted when instructed, verify the release, failed units and important services:

$ . /etc/os-release
$ printf 'release: %s %s\n' "$ID" "$VERSION_ID"
$ systemctl --failed --no-legend
$ systemctl is-active --quiet SERVICE_NAME
$ printf 'SERVICE_NAME status: %s\n' "$?"
SERVICE_NAME status: 0

Replace SERVICE_NAME with an actual service recorded before the change. Check application health, network access, scheduled jobs, mounts and monitoring as appropriate for the host. Compare the post-upgrade service list with the pre-upgrade record instead of assuming that a successful reboot means the application is healthy.

If the command reports a package or configuration problem, preserve its output and use the recovery path prepared before the upgrade: the provider console, a tested snapshot restore, or the documented backup procedure. Do not delete package caches, old kernels or backups while the new release is still being validated. Recovery is host-specific, so there is no safe universal undo command for a completed distribution upgrade.

7. Keep diagnostics separate from upgrade controls

--quiet reduces output, while --env=ENV passes a comma-separated list of environment assignments such as VAR1=VALUE1,VAR2=VALUE2 during the upgrade. Quiet output can make an unattended run harder to diagnose, and environment values can expose secrets in process records or logs. Use both only after checking the exact operational need and the sensitivity of the values.

--data-dir=DATA_DIR points the upgrader at a directory containing its data files. It is not a general backup location and should not be changed to an arbitrary directory in a production run. --proposed uses an upgrader from Ubuntu-proposed, so treat it as a test or troubleshooting choice rather than a routine upgrade flag.