How to upgrade Debian 11 to Debian 12 bookworm using CLI

See all Debian/Ubuntu Linux related FAQ
Debian Linux 12 “Bookworm” has been released. As of 23/July/2023, Debian 12.1 point was released too. The new version offers updated packages and five years of support. This page provides a step-by-step guide to updating Debian 11 Bullseye to Debian 12 Bookworm using command-line options, including upgrading all installed packages.

Tutorial details
Difficulty level Advanced
Root privileges Yes
Requirements Linux terminal
Category Package Manager
Prerequisites Debian Linux 11
OS compatibility Debian Linux
Est. reading time 10 minutes

What’s new in Debian 12?

  • Apache 2.4.57-2
  • Bash 5.2.15
  • BIND DNS Server 9.18
  • Emacs 27.1
  • GNOME desktop 43
  • KDE desktop/KDE Plasma 5.27
  • Libreoffice 7.4
  • Lighttpd 1.4.69
  • Linux kernel 6.1.0-9
  • LXDE 11
  • LXQt 1.2.0
  • MariaDB 10.11.3-1
  • MATE 1.26
  • Nginx 1.22 with brotli module
  • OpenSSH version 9.2p1-2
  • Perl 5.36.0
  • PHP 8.2
  • Postgresql 15
  • Python 3.11.2
  • Rustc 1.63
  • Vi IMproved (VIM) 9.0
  • Xfce 4.18.
Just to be clear, it is not possible to upgrade from Debian Linux version 10 directly to version 12. You will need to go through the Debian 10 to 11 upgrade first, and then upgrade from version 11 to version 12.

Upgrade Debian 11 to Debian 12 Bookworm

The procedure is as follows:

  1. Backup the system.
  2. Update existing packages and reboot the Debian 11 system.
  3. Edit the file /etc/apt/sources.list using a text editor and replace each instance of bullseye with bookworm. Next find the update line, replace keyword bullseye-updates with bookworm-updates. Finally, search the security line, replace keyword bullseye-security with bookworm-security.
  4. Update the packages index on Debian Linux, run:
    sudo apt update
  5. Prepare for the operating system minimal system upgrade, run:
    sudo apt upgrade --without-new-pkgs
  6. Finally, update Debian 11 to Debian 12 Bookworm by running:
    sudo apt full-upgrade
  7. Reboot the Linux system so that you can boot into Debian 12 Bookworm
  8. Verify that everything is working correctly.

Let us see all commands step by step to upgrade Debian 11 Bullseye to Debian 12 Bookworm safely running in the cloud or bare metal environment.

Step 1. Backup your system

Warning! It is essential to complete the backup process to avoid any data loss or installation failure. The responsibility for keeping verified backups lies with the user, as this is a fundamental lesson for sysadmins. The author and nixCraft cannot be held accountable for any issues that arise due to a lack of backup.

Backing up all data and system configurations is extremely important. To do this efficiently, cloud-based virtual machines can be quickly backed up and restored using snapshots. My preferred backup solution is rsnapshot, which works well for creating backups on both local and remote servers. Check out rsnapshot for more information. Check os version in Linux using the lsb_release command. For instance:
$ lsb_release -a
Here is what I see:

No LSB modules are available.
Distributor ID:	Debian
Description:	Debian GNU/Linux 11 (bullseye)
Release:	11
Codename:	bullseye

Note down the Linux kernel version too. Try the uname command:
$ uname -mrs
My Linux kernel version:

Linux 5.10.0-23-amd64 x86_64

Also note down the Debian version using the cat command:
$ cat /etc/debian_version
Outputs:
11.7

Step 2. Update ALL existing installed packages

To make the upgrade safer, you must remove non-Debian packages. For example, Google Chrome or VirtualBox is a non-Debian package installed using 3rd party repo. Those can create a problem. Here is how to find such pages:
$ sudo apt list '?narrow(?installed, ?not(?origin(Debian)))'
$ sudo apt-forktracer | sort

Fortunately, I don’t rely on Google Chrome, VirtualBox, or any third-party applications on Debian. However, if you use these apps, you should back up your data before upgrading. After upgrading, you can reinstall these packages if the Bookworm release supports them. Also, any package in hold status will create a problem with the upgrade procedure. Therefore, list all packages hold from upgrades using the apt-mark command as follows:
$ sudo apt-mark showhold | more
# OR #
$ sudo dpkg --get-selections | grep 'hold$' | more

Then you must delete or remove the host status for all listed packages one by one with the help of the following command:
$ sudo apt-mark unhold package_name
## OR ##
$ echo 'package_name install' | sudo dpkg --set-selections

See “apt-get hold back packages on Ubuntu / Debian Linux for more info. Before you upgrade your Debian version to 12, you must apply all security patches and pending upgrades to Debian 11 itself. Therefore, type the following apt command or apt-get command:
$ sudo apt update
$ sudo apt upgrade
$ sudo apt full-upgrade
$ sudo apt --purge autoremove

Reading package lists... Done
Building dependency tree... Done
Reading state information... Done
Calculating upgrade... Done
The following packages will be upgraded:
  libssl1.1 openssl
2 upgraded, 0 newly installed, 0 to remove and 0 not upgraded.
Need to get 2,413 kB of archives.
After this operation, 4,096 B disk space will be freed.
Do you want to continue? [Y/n] y
Get:1 http://mirrors.linode.com/debian-security bullseye-security/updates/main amd64 libssl1.1 amd64 1.1.1n-0+deb11u5 [1,559 kB]
Get:2 http://mirrors.linode.com/debian-security bullseye-security/updates/main amd64 openssl amd64 1.1.1n-0+deb11u5 [854 kB]
Fetched 2,413 kB in 0s (21.2 MB/s)
Reading changelogs... Done
Preconfiguring packages ...
(Reading database ... 30868 files and directories currently installed.)
Preparing to unpack .../libssl1.1_1.1.1n-0+deb11u5_amd64.deb ...
Unpacking libssl1.1:amd64 (1.1.1n-0+deb11u5) over (1.1.1n-0+deb11u4) ...
Setting up libssl1.1:amd64 (1.1.1n-0+deb11u5) ...
(Reading database ... 30868 files and directories currently installed.)
Preparing to unpack .../openssl_1.1.1n-0+deb11u5_amd64.deb ...
Unpacking openssl (1.1.1n-0+deb11u5) over (1.1.1n-0+deb11u4) ...
Setting up openssl (1.1.1n-0+deb11u5) ...
Processing triggers for man-db (2.9.4-2) ...
 
Processing triggers for libc-bin (2.31-13+deb11u6) ...##########################################
Reboot the Debian 11.x bullseye to apply the kernel and other updates using the “reboot” or “shutdown” command. For instance:
$ sudo systemctl reboot

Step 3. Update /etc/apt/sources.list file

To begin the upgrade process, it is necessary to reconfigure the source-list files of APT. You can view the current settings by using the commands cat command or more command. This will display the list of Debian 11 repo URLs.
$ sudo cat /etc/apt/sources.list
Outputs:

deb http://deb.debian.org/debian bullseye main
deb http://deb.debian.org/debian bullseye-updates main
deb http://deb.debian.org/debian-security/ bullseye-security main

The keyword bullseye indicates we are using an older version, 11. Hence, we must change all the references in this file from bullseye to bookworm using a text editor such as Vim or Nano. For example:
$ sudo cp -v /etc/apt/sources.list /root/sources.list-bakup.11.bullseye
$ sudo vim /etc/apt/sources.list

From:

deb http://deb.debian.org/debian bullseye main
deb http://deb.debian.org/debian bullseye-updates main
deb http://deb.debian.org/debian-security/ bullseye-security main

To:

deb http://deb.debian.org/debian bookworm main
deb http://deb.debian.org/debian bookworm-updates main
deb http://deb.debian.org/debian-security/ bookworm-security main

Save and close the file. You can also use the sed command to find and replace bullseye with bookworm as follows:
$ sudo sed -i'.bak' 's/bullseye/bookworm/g' /etc/apt/sources.list

Upgrading To Debian 12 Bookworm

Updating APT source list file to use Bookwork release

A note about the non-free-firmware repo

If you intend to use Debian 12 on either a desktop or server that requires non-free firmware for hardware such as WiFi, GPU, Sound, Nvida/AMD GPU, NIC and more, it is recommended to include the non-free firmware repository. Below is the updated file /etc/apt/sources.list file. The orange color repo config indicates that non-free firmware is required for your hardware. If you’re unsure about your hardware, I suggest adding those repositories.

deb http://deb.debian.org/debian bookworm main contrib non-free non-free-firmware
deb http://deb.debian.org/debian bookworm-updates main contrib non-free non-free-firmware
deb http://deb.debian.org/debian-security/ bookworm-security main contrib non-free non-free-firmware

Updating the package list

Finally, run the following command to get fresh apt repo data:
$ sudo apt update

Updating the package list for Debian 12 Linux

Click to enlarge

Step 4. Minimal system upgrade

The system provided the following message:

315 packages can be upgraded. Run 'apt list --upgradable' to see them.

Therefore, a two-part process is necessary to avoid removing large numbers of packages you want to keep. Therefore, first, run the following command to apply:
$ sudo apt upgrade --without-new-pkgs

Debian 11 to Debian 12 Minimal system upgrade command

Use a two-part process to avoid accidentally removing essential packages. Start by running apt upgrade –without-new-pkgs command (click to enlarge)

To complete the upgrade, please carefully follow the on-screen instructions. You may encounter questions such as “Would you like to restart the service?” or “Keep or erase configuration file options?” throughout the process. For instance, I was presented with a screen displaying new changes:

AWS Linode Debian 11.7 to Debian 12 upgrade APT changes

Read carefully and press “q” to exit this screen.

Please press ‘q‘ to exit and further you may see additional screens and dialogs too:

Restart Debian 12 services during package upgrades without asking

Ensure you choose the “Yes” option.

Can you explain why I receive prompts when upgrading the system?

Your system has some services that require a restart when specific libraries like libpam, libc, and libssl are updated. These restarts might cause service disruptions, so you will usually be asked to choose which services to restart during each upgrade. However, you can skip this prompt by selecting the “Yes” option. By doing so, all the necessary restarts will occur automatically, and you won’t be bothered with questions during each library upgrade. Here is another example, about GRUB package. A new version (/tmp/grub.nSxPVErDRh) of the configuration file /etc/default/grub is available, but the version installed currently has been locally modified. What do you want to do about the modified configuration file grub? Again review all options carefully. I typically chose the “keep the local version currently installed”:

A new version of GRUB config for Debian 12 bookworm prompt

Click to enlarge

Step 5. Upgrading Debian 11 to Debian 12

To fully update from Debian 11 to Debian 12, it’s necessary to make complete upgrades, rather than just minimum ones. This step is crucial for the upgrade process. To do this, enter the following command to ensure that the latest versions of all packages are installed and any potential dependencies are resolved. For example:
$ sudo apt full-upgrade

How to upgrade Debian 11 to Debian 12 Bookworm using the CLI

Click to enlarge

You might encounter more prompts that suggest restarting services or modifying existing configuration options. Make sure to review them carefully. For example, you may have the option to update or retain the OpenSSH configuration file:

What to do with OpenSSH config files on Debian 12. Replace or keep it

Are you considering replacing or keeping your OpenSSH config files on Debian 12? I decided to keep the orignal.

And you are done with the whole updating procedure. It is time to reboot the Linux system to boot into Debian Linux 12 bookworm. Before we restart the system, ensure there are no errors in the SSHD config file for the remote server:
$ sudo sshd -t
If there are no errors, you can proceed with rebooting the system. However, if there are any errors, it is important to fix them before rebooting. To do so, run:
$ sudo vim /etc/ssh/sshd_config
Verify again:
$ sudo sshd -t
Now reboot it after fixing any errors:
$ sudo systemctl reboot
Outputs:

Connection to 139.1xx.yyy.zz2 closed by remote host.
Connection to 139.1xx.yyy.zz2 closed.

Try running the ping command to get notification when your server comes back online:
$ ping -a server_IP_here
$ ping -a 139.1xx.yyy.zz2

Step 6. Verification

All done. It is time to confirm the upgrade. Type:
$ uname -mrs
Outputs:
Linux 6.1.0-10-amd64 x86_64
$ lsb_release -a

I get successful update confirmation:

No LSB modules are available.
Distributor ID:	Debian
Description:	Debian GNU/Linux 12 (bookworm)
Release:	12
Codename:	bookworm

Check Debian major and minor version too:
$ cat /etc/debian_version
Outputs:
12.1

After the upgrade, look out for all your apps and services. Therefore, verify all TCP/UDP ports are opened and services are running using the tail command or ss command or grep command/egrep command:

sudo ss -tulpn
sudo tail -f /var/log/mail.log
sudo tail -f /var/log/apache2/access_log
 
# look for errors if any
sudo grep 'error' /var/log/my_pyton_app/sales_app.log
sudo grep -E -i 'err|fail|warn|crit' /var/log/nginx/php_nixcraft_blog.log
 
# Check for service status
sudo systemctl status nginx.service
sudo systemctl status apache2.service
sudo systemctl status mariadb.service
 
# Use journalctl to query the contents of the systemd(1) journal
sudo journalctl
sudo journalctl -u sshd.service

A note about removing unwanted packages

WARNING! Although optional, it is vital to review packages that are no longer needed on your system. Failure to do so may result in the system breaking if the following command is executed.

Finally, clean up outdated packages using the apt command/apt-get command as follows:
$ sudo apt --purge autoremove

How to Upgrade Debian 11 Bullseye to Debian 12 Bookworm

A note about missing drivers or firmwares blobs

If you upgrade your system from Debian 11 to 12, particular firmware stored on your device may become disabled. You can check for disabled firmware in the kernel modules directory located at /lib/. For instance, there may be a Qualcomm firmware file named firmware-6.bin.disabled from the previous upgrade. To resolve this issue, you must reinstall or upgrade these files and then reboot your system. This also applies to proprietary drivers like NVidia. Therefore, it’s crucial to create backups and remain calm.

Summing up

And there you have it. We have successfully upgraded to Debian Linux 12. Updated Debian 12 version always brings new features and hardware support via Linux kernel. Hence, one must evaluate needs and then do upgrades. Debian Linux project also posted an in-depth guide that explains other issues one might face during installation. Make sure your read man pages using the man command or help command. For example:
$ man apt
$ man apt-get
$ man dpkg

I am running Debian version 12.x on the server side with LXD and Docker. Additionally, the updated versions of Python and PHP have been constructive. At least my experience is positive.

🥺 Was this helpful? Please add a comment to show your appreciation or feedback.

nixCrat Tux Pixel Penguin
Hi! 🤠
I'm Vivek Gite, and I write about Linux, macOS, Unix, IT, programming, infosec, and open source. Subscribe to my RSS feed or email newsletter for updates.

51 comments… add one
  • Jared Flack Nov 20, 2023 @ 15:00

    Great guide!

    I had the misfortune of the network interface link “name” changing from eth0 to enX0. So after reboot I couldn’t connect remotely. I would be a nice addition to the tutorial to check for that.

  • Carsten Feb 2, 2024 @ 8:19

    This guide is what I’m looking for to upgrade my system :)! I’m hosting a nextcloud on a pi 4 and need to upgrade before switching to a pi 5.
    I want to be sure only updating the OS and no other packages like PHP for example.
    Is this command doing the thing: sudo apt upgrade –without-new-pkgs ?

    Thank you!

    • 🛡️ Vivek Gite (Author and Admin) Vivek Gite Feb 2, 2024 @ 10:12

      No, it will upgrade php too. This is why you need to keep full backups. In case something is not working you can restore your data or go back to older version.

      • Carsten Feb 2, 2024 @ 15:41

        Ah ok. I would make a full backup anyway. I just would prefere only updating the OS. But I think that’s not possible.

  • N Feb 13, 2024 @ 5:47

    Perfect instructions to get my dev srv from buster to bookworm. Looking forward for another five years of flawless operation.
    Thank you very much for your time and effort.

  • Simon Mar 4, 2024 @ 7:27

    The thing that happened to me was that I didn’t have installed a package name “usrmerge”, I followed the instructions, and when usrmerge was used, the system some kind of broke, the messages it throws was about a duplicate between “/bin/package_name” and “/usr/bin/package_name”. I checked i did not have installed “usrmerge”; anyway after some two years backup buried on a IDE (old I know) I came back with a working system, so resume to upgrade I install usrmerge. Thats what happened to me.

  • Guillaume Mar 18, 2024 @ 4:21

    Perfect checklist
    (only issue I faced was on 1 specific server where the key password was not accepted anymore. Fixed it by updating kitty/putty – in case this can help… no need to try secure mode immediately ;-) )
    Thanks!

  • Nils Apr 15, 2024 @ 18:11

    Thanks for the great update guide – worked like a charm!

  • Pdater May 14, 2024 @ 5:47

    Wish Debian has a GUI software updater like Ubuntu that would this all for you.

Leave a Reply

Your email address will not be published. Required fields are marked *

Use HTML <pre>...</pre> for code samples. Your comment will appear only after approval by the site admin.