Upgrade from Debian 11 Bullseye to Debian 12 Bookworm

Debian 11 (bullseye) systems still need a controlled bridge release before they can move cleanly to newer Debian versions. To upgrade Debian 11 to Debian 12 (bookworm), start from a fully updated Bullseye system, replace only Debian archive sources, run Debian’s minimal upgrade step, then complete the full distribution upgrade with APT.

Debian 12 is now oldstable because Debian 13 (trixie) is the current stable release. The Debian release page currently lists Bookworm full support through June 10, 2026, with LTS through June 30, 2028. If your final goal is Debian 13, use this Bullseye-to-Bookworm upgrade first, then follow the current Debian 12 to 13 release notes. For the full upstream checklist, keep the official Debian 12 release notes open while you work.

Upgrade Debian 11 Bullseye to Debian 12 Bookworm

Confirm You Are Starting from Debian 11 Bullseye

Debian documents direct release upgrades only from the previous stable release. Confirm that the system is still Debian 11 (bullseye) before changing repositories:

. /etc/os-release
printf '%s %s\n' "$VERSION_ID" "$VERSION_CODENAME"

A Debian 11 system returns:

11 bullseye

If the system is Debian 10 (buster), upgrade to Debian 11 first. If the system is already Debian 12, do not use these Bullseye-to-Bookworm source changes. Readers searching for Debian 13 should complete Debian 11 to 12 first, then continue from Bookworm to Trixie.

Debian-based images such as Raspberry Pi OS or Armbian can carry their own bootloader, kernel, and vendor repository changes. Use their upgrade notes first, then apply Debian source changes only when those projects tell you the base Debian upgrade path is safe for that image.

Know What Changes Between Bullseye and Bookworm

Bookworm is a release upgrade, not a routine package refresh. The Debian 12 what’s new notes list over 11,000 new packages, more than 43,000 updated packages, the Linux 6.1 kernel series, OpenSSL 3.0, systemd 252, PHP 8.2, Python 3.11, and the new non-free-firmware archive component. That scale is why the backup, source cleanup, and package-health checks belong before the full upgrade.

Back Up Debian Before the Upgrade

A release upgrade changes packages, services, kernels, and configuration prompts. Back up personal data first, then save package and APT state so you can reconstruct what was installed if recovery is needed.

mkdir -p "$HOME/debian-11-upgrade-backup"
sudo tar -C / -cpf "$HOME/debian-11-upgrade-backup/etc.tar" etc
sudo tar -C / -cpf "$HOME/debian-11-upgrade-backup/dpkg.tar" var/lib/dpkg
sudo cp -a /var/lib/apt/extended_states "$HOME/debian-11-upgrade-backup/extended_states"
dpkg --get-selections '*' > "$HOME/debian-11-upgrade-backup/package-selections.txt"
apt-mark showmanual > "$HOME/debian-11-upgrade-backup/manual-packages.txt"

For desktop systems, a snapshot tool can make rollback easier than rebuilding the OS. The install Timeshift on Debian guide covers that option when your disk layout supports snapshots.

Server upgrades need a maintenance window. Stop or drain critical workloads, export database dumps, and pause automation that might run APT in the background. Stop monitoring tools that automatically restart services during package replacement. If the system uses unattended-upgrades on Debian, disable the timer temporarily before changing release sources.

Update Debian 11 Before Switching Repositories

Bring Bullseye to its latest package state before pointing APT at Bookworm. This reduces dependency conflicts and makes sure the archive keyring and package manager are current enough for the release transition.

sudo apt update
sudo apt upgrade
sudo apt full-upgrade
sudo apt install ca-certificates debian-archive-keyring apt-listchanges gpgv

Review any removals before confirming the full-upgrade step. If APT installs a new kernel or core system libraries, reboot into the updated Bullseye system before you edit sources:

sudo reboot

Check Package Health and Held Packages

Broken package states and held packages can stop a release upgrade halfway through. Run these checks while APT still points at Bullseye:

sudo dpkg --audit
apt-mark showhold

No output from either command is the clean state. If apt-mark showhold lists packages, unhold only the packages you are ready to upgrade:

sudo apt-mark unhold package-name

Replace package-name with the exact package shown by the hold check.

Review Current APT Sources

List active Bullseye, backports, testing, unstable, experimental, proposed-updates, and third-party source entries before editing anything. This avoids the common mistake of replacing bullseye inside vendor files that should be disabled or updated separately.

grep -R --include='*.list' --include='*.sources' -nE 'bullseye|backports|testing|unstable|sid|experimental|proposed-updates' /etc/apt/sources.list /etc/apt/sources.list.d 2>/dev/null || true

Disable Bullseye backports, Bullseye sloppy backports, proposed-updates, and non-Debian vendor repositories before the upgrade. Debian recommends removing old backports entries first, then adding Bookworm backports after the upgrade only if you still need them.

Check APT pinning separately. Pins that prefer testing, unstable, or a vendor archive can keep package candidates away from Bookworm during the release upgrade:

grep -R -nE '^(Package|Pin|Pin-Priority):' /etc/apt/preferences /etc/apt/preferences.d 2>/dev/null || true

No output means there are no explicit APT pins in those paths. If pins appear, review why they exist before changing them; a release upgrade is not the time to keep a testing, unstable, or old vendor priority in place by accident.

Also review installed packages that APT does not currently see as coming from Debian. This list is not perfect, but it helps identify local .deb installs and vendor packages that may need removal or a Bookworm-compatible source later:

apt list '?narrow(?installed, ?not(?origin(Debian)))'

For a vendor source such as Docker, disable the source file by renaming it, then refresh APT after the Bookworm upgrade is complete and re-add the vendor repository using Bookworm instructions:

sudo mv /etc/apt/sources.list.d/docker.sources /etc/apt/sources.list.d/docker.sources.disabled

The same pattern applies to other vendor files, but use the real filename from your system. For a broader cleanup workflow after the upgrade, see manage third-party APT repositories on Debian.

Write Debian 12 Bookworm Sources

Use one source-writing path, not both. Most Debian 11 systems still use the legacy /etc/apt/sources.list file, while some upgraded or manually converted systems use a DEB822 file such as /etc/apt/sources.list.d/debian.sources.

Do not keep active Bullseye and Bookworm Debian archive entries side by side unless you are following a specific troubleshooting workaround from the Debian release notes. Duplicate base sources can make APT select packages from the wrong release or report duplicate-target warnings.

Use Legacy sources.list on Typical Bullseye Systems

If the active Debian archive entries are in /etc/apt/sources.list, back up that file, then replace it with Bookworm entries that use the Debian CDN, the Bookworm security suite, and the Bookworm updates suite:

sudo cp -a /etc/apt/sources.list /etc/apt/sources.list.bullseye-backup
printf '%s\n' \
'deb https://deb.debian.org/debian bookworm main contrib non-free non-free-firmware' \
'deb https://security.debian.org/debian-security bookworm-security main contrib non-free non-free-firmware' \
'deb https://deb.debian.org/debian bookworm-updates main contrib non-free non-free-firmware' | sudo tee /etc/apt/sources.list > /dev/null

Use DEB822 Sources on Converted Systems

If the active Debian archive entries are already in /etc/apt/sources.list.d/debian.sources, back up and rewrite that DEB822 file instead. Keep /etc/apt/sources.list empty or commented so the two formats do not duplicate the same Debian archive suites.

sudo cp -a /etc/apt/sources.list.d/debian.sources /etc/apt/sources.list.d/debian.sources.bullseye-backup
printf '%s\n' \
'Types: deb' \
'URIs: https://deb.debian.org/debian' \
'Suites: bookworm bookworm-updates' \
'Components: main contrib non-free non-free-firmware' \
'Signed-By: /usr/share/keyrings/debian-archive-keyring.gpg' \
'' \
'Types: deb' \
'URIs: https://security.debian.org/debian-security' \
'Suites: bookworm-security' \
'Components: main contrib non-free non-free-firmware' \
'Signed-By: /usr/share/keyrings/debian-archive-keyring.gpg' | sudo tee /etc/apt/sources.list.d/debian.sources > /dev/null

Debian 12 moved many firmware packages into the non-free-firmware component. Keep contrib, non-free, and non-free-firmware during the upgrade if the Bullseye system used proprietary firmware or drivers. Some helper packages, including the firmware-b43-installer package, still live in contrib, while many redistributable firmware packages use non-free-firmware. The separate enable contrib and non-free repositories on Debian guide explains component choices after the release upgrade is finished.

Confirm the active Bookworm source lines:

grep -R --include='*.list' --include='*.sources' -nE 'bookworm|bullseye' /etc/apt/sources.list /etc/apt/sources.list.d 2>/dev/null || true

Bookworm lines should appear for the Debian archive. Bullseye lines should either be absent or clearly disabled in files you will not use during the upgrade.

Refresh APT with Bookworm Metadata

Refresh the package cache after the source change:

sudo apt update

Relevant output includes Bookworm release files:

Get:1 https://deb.debian.org/debian bookworm InRelease
Get:2 https://security.debian.org/debian-security bookworm-security InRelease
Get:3 https://deb.debian.org/debian bookworm-updates InRelease

If APT reports changed release metadata after adding non-free-firmware, accept the release-info change once:

sudo apt-get update --allow-releaseinfo-change

Run the Minimal Debian 12 Upgrade

Debian’s release notes recommend a two-part upgrade when a direct full upgrade could remove packages you want to keep. Start with the minimal upgrade, which updates packages that do not need new packages installed or old packages removed:

sudo apt upgrade --without-new-pkgs

If apt-listchanges opens a pager after downloads finish, read the package notes, then press q to return to the upgrade prompt.

Complete the Full Debian 12 Upgrade

After the minimal upgrade finishes, run the full release upgrade:

sudo apt full-upgrade

The full-upgrade command can install new packages and remove obsolete or conflicting packages. Read the removal list before you confirm, especially on desktops with graphics drivers or servers with third-party packages.

During the upgrade, APT may ask whether services should restart and whether package-maintainer configuration files should replace local versions. Keep local configuration files when you know they contain intentional changes; accept the maintainer version only when you want the new default or plan to merge changes manually afterward.

If you are unsure about a configuration prompt, write down the package and file path, keep the local file, and merge the maintainer changes after the system boots cleanly. Debian keeps old package versions of many changed configuration files with extensions such as .dpkg-old, .dpkg-dist, or .ucf-old.

Check the Debian Kernel Metapackage

Before rebooting, confirm that a Debian kernel metapackage is installed. This keeps future kernel security updates moving through APT instead of leaving the system pinned to one old kernel package.

dpkg -l 'linux-image*' | grep '^ii' | grep -i meta

On a 64-bit PC, look for an installed linux-image-amd64 row. The version field changes with Bookworm security updates, so the package name matters more than the exact revision.

If the command returns no output on a 64-bit PC, install the standard metapackage before rebooting:

sudo apt install linux-image-amd64

ARM64 systems normally use linux-image-arm64 instead. Check apt-cache search linux-image- | grep -i meta if you need to identify the correct architecture-specific metapackage.

Reboot into Debian 12 Bookworm

Reboot after the full upgrade and kernel metapackage check finish:

sudo reboot

Verify Debian 12 Bookworm After Reboot

Confirm the OS release first:

cat /etc/os-release

Relevant output should identify Debian 12 (bookworm):

PRETTY_NAME="Debian GNU/Linux 12 (bookworm)"
VERSION_ID="12"
VERSION="12 (bookworm)"
VERSION_CODENAME=bookworm
ID=debian

Check the running kernel:

uname -r

Most Bookworm systems report a kernel that starts with 6.1.0-, followed by a security-update revision and an architecture suffix such as amd64 or arm64.

Finish with a package-state check:

sudo dpkg --audit
apt list --upgradable

No dpkg --audit output and no pending package list beyond APT’s Listing... Done status indicate a clean post-upgrade package state.

Clean Up After the Debian 12 Upgrade

Clean up in stages instead of pasting one destructive command. First list removed packages that still have configuration files:

apt list '~c'

If the list contains only old removed packages you no longer need, purge those leftover configuration files. Purging removed packages can also delete package-owned log files, so back up anything you need before confirming:

sudo apt purge '~c'

List obsolete or locally created packages separately. Review this output carefully before removing anything, because local packages and vendor packages can appear here after a release upgrade:

apt list '~o'

Preview autoremovable packages before deleting them:

sudo apt autoremove --dry-run

If the dry run lists only obsolete libraries, transitional packages, and old dependencies you no longer need, run the cleanup:

sudo apt autoremove

Readers who removed Bullseye backports before the upgrade can add Bookworm backports later if they need newer kernels, drivers, or selected applications. Use the dedicated guide to install Debian backports and experimental repositories instead of reusing old Bullseye entries.

Troubleshoot Debian 11 to 12 Upgrade Issues

APT Reports a Changed Non-Free Component

When Bookworm sources add non-free-firmware, APT can warn that repository metadata changed:

Repository 'https://deb.debian.org/debian bookworm InRelease' changed its 'non-free component' value from 'non-free' to 'non-free non-free-firmware'

This warning is expected when the component list changes during the Bullseye-to-Bookworm transition. Accept the release-info change once, then rerun the normal update:

sudo apt-get update --allow-releaseinfo-change
sudo apt update

APT Says There Is Not Enough Free Space

A full desktop upgrade can need several gigabytes across the package cache and installed package set. If APT stops with this error, clear the old package cache first:

E: You don't have enough free space in /var/cache/apt/archives/.

sudo apt clean
df -h / /var /var/cache/apt/archives

If space is still tight, remove large applications you can reinstall later, move logs out of /var/log/, or use Debian’s temporary package-cache workaround from the release notes.

Full Upgrade Fails with Immediate Configuration Error

Debian documents this failure during some Bookworm upgrades:

E: Could not perform immediate configuration on 'package'. Please see man 5 apt.conf under APT::Immediate-Configure for details.

Retry the full upgrade with immediate configuration disabled for that run:

sudo apt full-upgrade -o APT::Immediate-Configure=0

Third-Party Repository Has No Bookworm Release File

Vendor repositories can block apt update if they do not publish Bookworm metadata or if the old Bullseye source remained enabled:

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.

Find the source file that contains the failing host:

grep -R --include='*.list' --include='*.sources' -n 'example.com' /etc/apt/sources.list.d /etc/apt/sources.list 2>/dev/null

Disable that specific vendor file, then refresh APT again:

sudo mv /etc/apt/sources.list.d/vendor.sources /etc/apt/sources.list.d/vendor.sources.disabled
sudo apt update

Replace vendor.sources with the actual filename from the grep output. For Docker specifically, the install Docker on Debian guide keeps the repository setup aligned with the active Debian release.

Held or Broken Packages Stop the Upgrade

If APT reports dependency problems, repair package configuration first:

sudo dpkg --configure --pending
sudo apt --fix-broken install

Check held packages again, then rerun the full upgrade:

apt-mark showhold
sudo apt full-upgrade

NVIDIA Driver or CUDA Problems After Upgrade

Graphics failures after the first Bookworm boot often involve old NVIDIA or CUDA packages, especially if they came from a vendor repository or .run installer rather than Debian’s archive.

Check installed NVIDIA and CUDA packages:

dpkg -l | grep '^ii' | grep -E 'nvidia|cuda'

If the desktop cannot start and you need to return to a bootable graphical session, remove the installed NVIDIA driver packages and reboot:

sudo apt purge '~nnvidia'
sudo apt autoremove
sudo reboot

Systems installed with NVIDIA’s .run file may also have the vendor uninstaller:

if [ -x /usr/bin/nvidia-uninstall ]; then
    sudo /usr/bin/nvidia-uninstall
else
    printf 'No NVIDIA .run uninstaller found at /usr/bin/nvidia-uninstall\n'
fi

CUDA installations under /usr/local/cuda-* can have their own uninstallers. List the installed directories first, set the directory that matches your system, then run that version’s uninstaller:

ls -d /usr/local/cuda-* 2>/dev/null
CUDA_DIR=/usr/local/cuda-12.0
if [ -x "$CUDA_DIR/bin/cuda-uninstall" ]; then
    sudo "$CUDA_DIR/bin/cuda-uninstall"
else
    printf 'No CUDA uninstaller found at %s\n' "$CUDA_DIR/bin/cuda-uninstall"
fi

Replace 12.0 in CUDA_DIR with the version shown on your system. After the desktop boots normally, reinstall a Bookworm-compatible driver from Debian’s repositories or use the current install NVIDIA drivers on Debian workflow. CUDA developers can use the separate guide to install CUDA on Debian.

Conclusion

Debian 12 Bookworm is running with Bookworm package sources, a current Debian kernel metapackage, and cleaned-up package state. From here, re-enable only the third-party repositories that publish Bookworm packages, restore maintenance tasks such as unattended upgrades, and use Bookworm as the bridge if you plan to continue onward to Debian 13.