Upgrading from Debian 11 Bullseye to Debian 12 Bookworm brings significant improvements to your system, including the Linux 6.1 LTS kernel, updated desktop environments, refreshed software packages, and enhanced security features. By the end of this guide, you will have a fully upgraded Debian 12 system with verified functionality, clean package management, and any common issues resolved.
This guide walks through preparing your system, updating APT sources, performing the distribution upgrade, and verifying success. You will also learn how to clean up obsolete packages and troubleshoot issues with Nvidia drivers or third-party repositories. For complete details on what’s new, see the official Debian 12 release notes.
Before You Begin: Back Up Your System
Before starting any major distribution upgrade, create a complete backup of your important data and system configuration files. While this upgrade process works reliably for most users, hardware differences and third-party software can occasionally cause issues. Debian does not officially support downgrades from Bookworm to Bullseye, so a backup provides your safety net.
Recommended backup steps: Back up your home directory, any custom configurations in
/etc/, and database dumps if you run a server. Consider using Timeshift on Debian to create a system snapshot you can restore if needed.
Server users: Stop critical services such as Nginx, Apache, MySQL, and PHP-FPM before proceeding. Back up all configuration files and databases. If you use unattended-upgrades on Debian, temporarily disable automatic updates during the upgrade process. Performing the upgrade during a maintenance window reduces the risk of service disruption.
Step 1: Update Debian 11 System Packages
First, ensure your current Debian 11 Bullseye installation runs the latest available packages. This step reduces the chance of conflicts during the distribution upgrade by bringing all packages to their current Bullseye versions before switching repositories.
Run the following command in your terminal:
sudo apt update && sudo apt upgradeReview the list of packages to upgrade and confirm when prompted. If the update installs a new kernel or core system libraries, reboot your system to apply the changes before continuing:
sudo rebootStep 2: Modify sources.list for Debian 12 Bookworm
Next, update your APT sources to point to Debian 12 Bookworm repositories instead of Bullseye. Rather than manually editing the file, use the sed command to replace all occurrences automatically:
sudo sed -i 's/bullseye/bookworm/g' /etc/apt/sources.listThis command finds every instance of “bullseye” in your sources file and replaces it with “bookworm”, pointing your system to the new Debian 12 repositories.
Enable Non-Free and Contrib Repositories (Optional)
If you need access to proprietary firmware, drivers, or other non-free software, verify that the contrib and non-free-firmware components are enabled. For more details on these repositories, see our guide on enabling contrib and non-free repos on Debian.
Debian 12 introduces a
non-free-firmwarecomponent that separates firmware packages from other non-free software. This makes it easier to include only hardware firmware without enabling all non-free packages. In Debian 11 Bullseye, thenon-freecomponent included firmware, so thenon-free-firmwarecomponent does not exist there. The upgrade process automatically handles this transition.
Check if these components are already present in your sources file:
grep "deb http://deb.debian.org/debian/ bookworm main contrib non-free-firmware" /etc/apt/sources.listIf the command returns no output, you have not added these components yet. Add them using the following commands:
sudo sed -i '/deb http:\/\/deb.debian.org\/debian\/ bookworm main/ s/$/ contrib non-free-firmware/' /etc/apt/sources.list
sudo sed -i '/deb-src http:\/\/deb.debian.org\/debian\/ bookworm main/ s/$/ contrib non-free-firmware/' /etc/apt/sources.listAfter running these commands, your sources file will include contrib and non-free-firmware alongside the main repository. Verify the result by viewing your sources file:
cat /etc/apt/sources.listExpected output showing a properly configured Debian 12 sources file:
deb http://deb.debian.org/debian/ bookworm main contrib non-free-firmware deb-src http://deb.debian.org/debian/ bookworm main contrib non-free-firmware deb http://security.debian.org/debian-security bookworm-security main contrib non-free-firmware deb-src http://security.debian.org/debian-security bookworm-security main contrib non-free-firmware deb http://deb.debian.org/debian/ bookworm-updates main contrib non-free-firmware deb-src http://deb.debian.org/debian/ bookworm-updates main contrib non-free-firmware
Step 3: Run the Upgrade to Debian 12 Bookworm
With your sources updated, synchronize the package cache with the new Debian 12 repositories:
sudo apt updateYou should see output confirming that APT is accessing the Bookworm repositories. The output will show new release files downloading:
Hit:1 http://deb.debian.org/debian bookworm InRelease Get:2 http://security.debian.org/debian-security bookworm-security InRelease [48.0 kB] Get:3 http://deb.debian.org/debian bookworm-updates InRelease [55.4 kB] ...
After the update completes, run the full distribution upgrade:
sudo apt full-upgradeThe full-upgrade command handles package removals and additions needed to complete the distribution upgrade, unlike a standard upgrade which only updates existing packages. APT will display the number of packages to upgrade, install, and remove, along with the total download size. On a typical desktop installation, expect to download 1-3 GB of packages. A server with fewer packages will download less.
During the upgrade, you may see prompts about restarting services or handling configuration file changes:
Restarting services during package upgrades Which services should be restarted? [*] dbus.service [ ] cron.service [ ] ssh.service
For most desktop systems, accepting the defaults works well. For servers, carefully review which services will restart to minimize downtime for critical applications.
Configuration file handling: If you modified default configuration files, APT will ask whether to keep your version or install the package maintainer’s version. For most users, keeping your existing configuration preserves customizations. Choose the maintainer’s version only if you want fresh defaults or suspect your modifications caused issues.
Step 4: Reboot to Finalize the Upgrade
After the upgrade process completes, reboot your system to load the new Debian 12 kernel and apply all system changes:
sudo rebootDuring the reboot, you will notice the new Debian 12 boot screen (if using GRUB) and the system loading the Linux 6.1 kernel series.
Step 5: Verify the Upgrade
After your system restarts, confirm that the upgrade completed successfully by checking the OS release information:
cat /etc/os-releaseExpected output confirming Debian 12 Bookworm:
PRETTY_NAME="Debian GNU/Linux 12 (bookworm)" NAME="Debian GNU/Linux" VERSION_ID="12" VERSION="12 (bookworm)" VERSION_CODENAME=bookworm ID=debian HOME_URL="https://www.debian.org/" SUPPORT_URL="https://www.debian.org/support" BUG_REPORT_URL="https://bugs.debian.org/"
Additionally, verify the kernel version to confirm you are running the Debian 12 kernel:
uname -rExpected output showing a 6.1.x kernel:
6.1.0-xx-amd64
The exact kernel version number varies based on the latest security updates. Any version starting with 6.1 confirms a successful upgrade to Debian 12. ARM users will see
6.1.0-xx-arm64instead.
Step 6: Clean Up Obsolete Packages (Recommended)
After the upgrade, your system may contain old packages you no longer need. Removing these packages frees disk space and reduces potential security risks from unmaintained software. The --purge flag removes configuration files along with the packages, resulting in a cleaner system:
sudo apt --purge autoremoveReview the list of packages before confirming. In most cases, these are transitional packages, old library versions, and dependencies that no installed software requires. The command output will show you exactly what will be removed.
Troubleshooting Upgrade Issues
While most upgrades complete without issues, certain hardware configurations and third-party software can cause problems. This section covers the most common issues users encounter and provides diagnostic steps to identify and resolve them.
Nvidia Driver Conflicts
Nvidia proprietary drivers from Debian 11 may conflict with the newer kernel in Debian 12. If your system fails to boot to a graphical desktop, displays a black screen, or shows graphics corruption after the upgrade, the Nvidia driver is likely the cause.
First, check whether you have Nvidia drivers installed and identify the installed version:
dpkg -l | grep nvidiaExample output showing installed Nvidia packages:
ii nvidia-driver 525.147.05-7 amd64 NVIDIA metapackage ii nvidia-kernel-dkms 525.147.05-7 amd64 NVIDIA binary kernel module DKMS source
If you see Nvidia packages listed, remove them to restore the system to a working state:
sudo apt autoremove nvidia* --purgeThis command removes all Nvidia driver packages and their configuration files. After removal, your system will use the open-source nouveau driver, which provides basic graphics functionality.
Verify the removal completed successfully:
dpkg -l | grep nvidiaThe command should return no output if you removed all Nvidia packages successfully. Reboot to apply the change:
sudo rebootNvidia Drivers Installed via .run File
If you installed Nvidia drivers using the official .run installer from Nvidia’s website rather than through APT, use the Nvidia uninstaller:
sudo /usr/bin/nvidia-uninstallFollow the prompts to complete the removal process. The uninstaller will restore the nouveau driver blacklist file changes.
CUDA Toolkit Removal
If you also have the CUDA toolkit installed and encounter issues, you may need to remove it as well. First, locate your CUDA installation directory:
ls /usr/local/cuda*The output shows installed CUDA versions, for example:
/usr/local/cuda-11.8 /usr/local/cuda-12.0
Run the uninstaller for your specific CUDA version:
sudo /usr/local/cuda-12.0/bin/cuda-uninstallReplace 12.0 with your actual CUDA version from the previous command’s output.
Reinstalling Nvidia Drivers After Upgrade
After your system boots correctly with the nouveau driver, you can install the Debian 12 Nvidia drivers. The Debian 12 repositories include updated driver versions compatible with the 6.1 kernel. For CUDA development, refer to our guide on installing CUDA on Debian.
Third-Party Repository Issues
If you have third-party repositories configured (such as Docker, VS Code, or other vendor repos), they may cause errors during apt update if they do not yet support Debian 12 Bookworm.
Common error messages include:
E: The repository 'https://example.com/repo bookworm Release' does not have a Release file. N: Updating from such a repository can't be done securely, and is therefore disabled by default.
To identify which repositories are causing issues, check for files in the sources directory:
ls /etc/apt/sources.list.d/Temporarily disable problematic repositories by commenting them out or removing the file. For example, to disable a Docker repository:
sudo mv /etc/apt/sources.list.d/docker.sources /etc/apt/sources.list.d/docker.sources.disabledComplete the upgrade, then re-enable repositories once the vendor releases Bookworm-compatible packages. For information on Docker installation on Debian, which includes proper repository configuration for your Debian version, see our dedicated guide.
Broken Package Dependencies
If the upgrade process fails partway through or you encounter dependency issues, try fixing broken packages:
sudo apt --fix-broken installThen continue the upgrade:
sudo apt full-upgradeIf specific packages prevent the upgrade from completing, you can temporarily remove them and reinstall after the upgrade finishes:
sudo apt remove problematic-package-nameConclusion
You have successfully upgraded from Debian 11 Bullseye to Debian 12 Bookworm. Your system now runs the Linux 6.1 LTS kernel with improved hardware support, updated desktop environments and applications, and continued security updates through Debian’s standard support cycle. With obsolete packages removed and any driver conflicts resolved, your Debian installation is ready for production use.
