Debian 11 (Bullseye) is winding down. Debian 12 (Bookworm) brings updated kernels, newer core libraries, the explicit non-free-firmware component, and a longer security horizon. If you are running QuickBox Pro on a server that is still on Bullseye, this is the upgrade path that has shipped cleanly across hundreds of installs.
The goal of this guide is boring. A Debian point-release upgrade should not surprise you. Follow each step in order, do not skip the screen session if you are remote, and you will end up on Bookworm with your services and configurations intact.
Prerequisites
Before you start, confirm:
- ●You are on Debian 11 (Bullseye): verify with
cat /etc/os-release - ●You have root access or a user with
sudo - ●You have SSH access or a console you trust
- ●You took a backup or VPS snapshot within the last hour
- ●You have at least 1–2 GB of free disk space
- ●You are comfortable reading apt output and resolving conflicts
Important
If you do not have a current backup, stop and take one. A failed dist-upgrade on a remote box without a snapshot is a long evening you do not need.
Step 1: Confirm Your Current Version
cat /etc/os-release
You should see:
PRETTY_NAME="Debian GNU/Linux 11 (bullseye)"
If the line says anything other than bullseye, do not continue with this guide.
Step 2: Start a Screen Session
If you are connected over SSH, run the rest of the upgrade inside screen. If your connection drops mid-upgrade, you can reattach and finish.
sudo apt update && sudo apt install screen -y
screen -S debian-upgrade
To detach without stopping the session: CTRL + A, then D. To reattach later: screen -r debian-upgrade.
Tip
If screen -ls shows the session is still attached elsewhere (after a dropped SSH), use screen -d -r debian-upgrade to force-detach and reattach.
Step 3: Update the Bullseye System
Before moving to a new release, fully patch the current one.
sudo apt update && sudo apt upgrade -y && sudo apt full-upgrade -y && sudo apt autoremove -y
This closes out any pending updates so the version transition starts from a known-clean state.
Step 4: Reboot If Kernel Updates Were Installed
If the previous step pulled in a new kernel, reboot before continuing.
sudo reboot
Reconnect over SSH, rejoin your screen session:
screen -r debian-upgrade
Step 5: Switch APT Sources to Bookworm
Debian release upgrades are driven by changing the codename in your APT sources. Back up first, then rewrite.
sudo cp /etc/apt/sources.list /etc/apt/sources.list.bak
sudo sed -i 's/bullseye/bookworm/g' /etc/apt/sources.list
Debian 12 introduced a separate non-free-firmware component. If your sources reference non-free, add the new component:
sudo sed -i 's/non-free/non-free non-free-firmware/g' /etc/apt/sources.list
Verify the rewrite:
grep bookworm /etc/apt/sources.list
You should see bookworm entries and no bullseye entries.
Note
If you have files in /etc/apt/sources.list.d/, repeat the sed against those too. Many third-party repos still pin to Bullseye and may need to be disabled or replaced.
Step 6: Refresh Package Lists
sudo apt update
The package list will now come from Bookworm. apt may report new components; that is expected.
Step 7: Run the Upgrade Without Losing Configurations
The most common cause of a borked dist-upgrade is interactive prompts asking you whether to overwrite a configuration file. On a server, you almost always want to keep the existing config and resolve any drift afterwards.
Minimal upgrade first (no new packages, just version updates):
sudo DEBIAN_FRONTEND=noninteractive apt upgrade --without-new-pkgs -y \
-o Dpkg::Options::="--force-confdef" \
-o Dpkg::Options::="--force-confold"
Then the full distribution upgrade:
sudo DEBIAN_FRONTEND=noninteractive apt full-upgrade -y \
-o Dpkg::Options::="--force-confdef" \
-o Dpkg::Options::="--force-confold"
The flag combination keeps your existing config files and uses package defaults where one exists. After the upgrade you can diff against the new defaults at your leisure.
Step 8: Clean Up
sudo apt autoremove -y && sudo apt autoclean
This removes orphaned packages and clears stale apt caches. On a small VPS this can recover a surprising amount of disk.
Step 9: Reboot Into Bookworm
sudo reboot
Reconnect after the reboot.
Verification
Confirm the upgrade.
cat /etc/os-release
You should now see:
PRETTY_NAME="Debian GNU/Linux 12 (bookworm)"
Kernel version:
uname -r
APT sources reference Bookworm and no Bullseye:
grep bookworm /etc/apt/sources.list
grep bullseye /etc/apt/sources.list
The second command should produce no output.
Troubleshooting
| Problem | Fix |
|---|---|
| SSH dropped mid-upgrade | Reconnect, then screen -r debian-upgrade to resume |
| Broken dependencies | sudo apt --fix-broken install |
| Held-back packages | sudo apt full-upgrade again to resolve them |
| Repo errors after sed | Check /etc/apt/sources.list.d/*.list for stale third-party repos |
| Need to roll back sources | sudo cp /etc/apt/sources.list.bak /etc/apt/sources.list && sudo apt update |
Warning
Rolling back sources does not roll back installed packages. A failed Bookworm upgrade on a production box is a restore-from-snapshot situation, not a sources rollback situation.
Why This Upgrade Path
The screen + noninteractive + confdef/confold combination has shipped cleanly on QuickBox Pro deployments across more than a hundred VPS providers and on-the-metal installs. The steps look long because each one is documented; the actual work fits in a single screen session and is mostly waiting on apt.
Keep your servers patched. Keep your snapshots fresh. Keep your config files in version control if you can. Bookworm will be supported through 2028.