To start, read the official release notes.
If your system is "vanilla Debian plus maybe a handful of 3rd-party repos", then this guide for a simple upgrade to Debian 12 "bookworm" from Debian 11 "bullseye" can be helpful. 3rd-party repos are handled with a find command.
If you are on a fork of Debian such as RasPI OS, use their instructions, not this gist.
Note upgrade is only supported from Debian 11 to Debian 12. If you are on Debian 10, upgrade to Debian 11 first and make sure to change the security repo as per the release notes. Then once on Debian 11, you can upgrade to Debian 12.
From Debian 12, you can upgrade to Debian 13.
This guide is only for the OS itself. Applications are as plentiful as sand on the beach, and they may all require additional steps. Plan for that.
- Check free disk space
df -h
5 GiB free is a conservative amount. sudo apt clean and sudo apt autoremove can be used to free some disk space.
On a server with only docker installed, even 1 GiB free was sufficient. Do err on the side of caution here, however.
- Identify any 3rd-party repos that may need to be updated. They'll be changed with a
findcommand, below.
ls /etc/apt/sources.list.d
- Update current distribution
sudo apt update && sudo apt full-upgrade
If this brought in a new kernel, sudo reboot - otherwise continue
- Optional: Start a screen session
So that an SSH disconnect doesn't stop your upgrade halfway through, you can run in screen:
sudo apt install -y screen && screen
- Change repo to bookworm, from bullseye.
sudo sed -i 's/bullseye/bookworm/g' /etc/apt/sources.list
- Add
non-free-firmwareifnon-freeis currently in use
sudo sed -i '/non-free/ s/$/ non-free-firmware/' /etc/apt/sources.list
- Change all 3rd-party repos
This assumes the repos have bookworm versions. Run
sudo apt updateafter the change to bookworm to confirm, and deal with any repos that aren't available in bookworm.
sudo find /etc/apt/sources.list.d -type f -exec sed -i 's/bullseye/bookworm/g' {} \;
Run sudo apt update and if it fails on some repos because they don't have bookworm versions, disable them for now, then test again. Keep monitoring disabled repos and bring them to bookworm when they are ready.
- Update Debian
For the following, say Yes to restarting services, and keep existing config files when prompted. If using msmtp, acknowledge warnings. AppArmor for msmtp worked for me.
sudo apt update && sudo apt full-upgrade
- If you use mdadm with more than one ESP
Having more than one ESP (EFI System Partition) is an unusual setup. If you are certain you have only one ESP, move on to the next step.
If you have multiple ESPs for this copy of Debian, you can ensure they are all upgraded. Debian 12 uses grub 2.06, as does Debian 11. Skipping this
step is not fatal.
- Reboot
sudo reboot
- Clean up old repos
sudo apt autoremove && sudo apt clean
Config ansible.cfg:
[defaults]
interpreter_python = /usr/bin/python3
Playbook bookworm.yml:
---
- name: Upgrade to Debian bookworm
hosts: all
serial: 1
gather_facts: false
roles:
- base/upgrade_bookworm
Role base/upgrade_bookworm/tasks/main.yml:
---
- name: Get distribution version
setup:
filter: ansible_distribution*
- name: Skip if not Debian 11
meta: end_host
when: ansible_distribution != 'Debian' or ansible_distribution_major_version != '11'
- name: apt clean
apt:
clean: yes
become: yes
- name: Get filesystem facts
setup:
filter: ansible_mounts
- name: Fail if free space on / is below 5 GiB
ansible.builtin.assert:
that:
- item.size_available > (5 * 1024 * 1024 * 1024)
fail_msg: "Free disk space on {{ item.mount }} is below 5 GiB"
loop: "{{ ansible_mounts }}"
when: item.mount == "/"
- name: All apt packages up to date
apt:
upgrade: dist
update_cache: yes
become: yes
- name: apt autoremove
apt:
autoremove: yes
become: yes
- name: apt clean
apt:
clean: yes
become: yes
- name: Check if reboot required
ansible.builtin.stat:
path: /run/reboot-required
get_checksum: no
register: reboot_required_file
- name: Reboot if required
ansible.builtin.reboot:
msg: "Reboot initiated by Ansible"
connect_timeout: 5
reboot_timeout: 600
pre_reboot_delay: 0
post_reboot_delay: 60
test_command: whoami
when: reboot_required_file.stat.exists
become: true
- name: Switch OS from bullseye to bookworm
ansible.builtin.replace:
path: /etc/apt/sources.list
regexp: 'bullseye'
replace: 'bookworm'
become: yes
- name: Add non-free-firmware if non-free is in use
ansible.builtin.replace:
path: /etc/apt/sources.list
regexp: '(.*non-free.*)'
replace: '\1 non-free-firmware'
become: yes
- name: Find all 3rd-party repos
ansible.builtin.find:
paths: /etc/apt/sources.list.d
patterns: '*'
recurse: no
register: third_party_repos
- name: Switch 3rd-party repos from bullseye to bookworm
ansible.builtin.replace:
path: "{{ item.path }}"
regexp: 'bullseye'
replace: 'bookworm'
loop: "{{ third_party_repos.files }}"
loop_control:
label: "{{ item.path }}"
become: yes
- name: Use apt to move to bookworm
apt:
upgrade: dist
update_cache: yes
become: yes
- name: Get distribution version
setup:
filter: ansible_distribution*
- name: Fail if not Debian 12
assert:
that:
- ansible_distribution_major_version == '12'
fail_msg: "Upgrade to Debian 12 failed"
- name: apt autoremove
apt:
autoremove: yes
become: yes
- name: apt clean
apt:
clean: yes
become: yes
- name: Re-enable msmtp apparmor profile
ansible.builtin.file:
path: /etc/apparmor.d/disable/usr.bin.msmtp
state: absent
become: yes
- name: Restart apparmor service
ansible.builtin.systemd:
name: apparmor
state: restarted
become: yes
- name: Reboot on bookworm
ansible.builtin.reboot:
msg: "Reboot initiated by Ansible"
connect_timeout: 5
reboot_timeout: 600
pre_reboot_delay: 0
post_reboot_delay: 60
test_command: whoami
become: yes
- name: Pause for 5 minutes for staggered upgrades
pause:
minutes: 5
I checked my
ansible.cfg. I have that set, but didn't document it. Oop. Added that, thanks for pointing it out @hmoffatt