==%hide Debian upgrade ==
====== Upgrading Debian 12 (bookworm) to Debian 13 (trixie) ======
This guide describes an in-place upgrade of the Base OS operating system from Debian 12 (bookworm) to Debian 13 (trixie) on Unipi devices, without reinstalling the system. The procedure is common to most product lines; steps that differ between lines are marked at the relevant step and summarised in the overview at the end of the page.
{{ :files:img_warning-line_b.png?nolink |}}
{{ :en:hw:01_safety-instructions_ISO-7010-W001.png?nolink |/!\}}
**Attention:** \\
**These steps are not supported for Mervis platform!**
----
Upgrading to Debian 13 invalidates the Mervis license on the Unipi Gate, Unipi Neuron and Unipi 1.1 / Lite lines. The Unipi Patron line should not be affected by this change. Consider the impact on devices operated with Mervis before upgrading.
{{ :files:img_warning-line_b.png?nolink |}}
{{ :en:hw:08_safety-instructions_pseudo-ISO-7010-info.png?nolink |(i)}}
**Note:** \\
The procedure assumes a standard, fully updated Base OS on Debian 12 (bookworm) with no custom kernel and no third-party APT sources. The steps were verified on Base OS // *-base-os_12.20251103.1//.
===== Supported product lines =====
* Unipi Patron
* Unipi Neuron
* Unipi Gate
Unipi Edge ships with Debian 13 (trixie) only, so this guide does not apply to it.
{{ :files:img_warning-line_b.png?nolink |}}
{{ :en:hw:08_safety-instructions_pseudo-ISO-7010-info.png?nolink |(i)}}
**Note:** \\
On the Unipi 1.1 / Lite line the upgrade to Debian 13 is also possible, but its functionality is not guaranteed. During the transition the Raspberry Pi kernel must be replaced with the Unipi kernel, which carries the risk that the device will not work correctly after the upgrade.
===== Upgrade procedure =====
==== 1. Updating the current system ====
Before moving to the new release, updated all packages to their latest version within Debian 12. This prevents unnecessary conflicts during the release upgrade. Rebooted the device afterwards.
sudo apt update && sudo apt upgrade -y
sudo reboot
==== 2. Removing the raspberrypi.list source (Neuron only) ====
On Raspberry Pi–based lines, the //raspberrypi.list// source is removed, as it is not available for Debian 13. This step applies to the **Unipi Neuron** line; it is skipped on the Unipi Patron and Unipi Gate lines.
sudo rm /etc/apt/sources.list.d/raspberrypi.list
==== 3. Switching the APT sources to trixie ====
In the APT sources, the name //bookworm// is replaced with //trixie//. This points the upgrade at the Debian 13 packages.
sudo sed -i 's/bookworm/trixie/g' /etc/apt/sources.list /etc/apt/sources.list.d/debian-nonfree.list /etc/apt/sources.list.d/unipi.list
==== 4. Upgrading the release ====
The package list is loaded from the new sources and the release upgrade to Debian 13 is performed. The upgrade may take a while.
sudo apt update
sudo apt dist-upgrade
==== 5. Removing the Unipi source and installing the trixie kernel ====
The //unipi.list// source is removed and the Unipi kernel intended for Debian 13 is installed. The exact set of packages differs per product line.
sudo rm /etc/apt/sources.list.d/unipi.list
* **Unipi Patron** and **Unipi Neuron** – kernel and modules: \\ ''sudo apt install unipi-kernel=6.12.101.0~trixie* unipi-kernel-modules=3.6~6.12.101.0~trixie*''
* **Unipi Gate** – kernel only: \\ ''sudo apt install unipi-kernel=6.12.101.0~trixie*''
==== 6. Verification before rebooting ====
Before rebooting, it is verified that the upgrade completed without errors and that the correct kernel and bootloader versions are installed. The device is rebooted only after a successful check.
{{ :files:img_warning-line_b.png?nolink |}}
{{ :en:hw:01_safety-instructions_ISO-7010-W001.png?nolink |/!\}}
**Attention:** \\
Do not reboot the device until the checks pass. Rebooting with a damaged or incorrect bootloader (u-boot) or kernel may leave the device unable to boot, requiring it to be re-flashed.
Package state check – verify that no package is left in an in-progress (broken) state, i.e. half-installed or not configured. The output should be empty. Leftovers from removed packages (state ''rc'', where only the configuration remains) are harmless:
sudo dpkg --audit
More importantly, verify that no packages from Debian 12 remain on the device. The following command lists installed packages whose version still carries the //deb12// marker (e.g. ''1.2.3+deb12u1''); the output should be empty:
dpkg -l | grep -e deb12 -e bookworm
Verify that userspace has switched to trixie – the ''VERSION_CODENAME'' field is expected to read //trixie//:
cat /etc/os-release
Kernel and bootloader version check – the version of the installed //unipi-kernel// and //unipi-u-boot// packages must contain the string ''~trixie'' (the suffix matches the product line; on the Unipi Patron line it is e.g. ''2026.01.6~trixie-patron''). If either package still shows a Debian 12 version, the kernel or bootloader was not upgraded and the device must **not** be rebooted. On lines without the u-boot bootloader the //unipi-u-boot// package is not listed:
dpkg -l unipi-kernel unipi-u-boot
==== 7. Reboot ====
After a successful check, the device is rebooted and boots into Debian 13.
sudo reboot
==== 8. Verification after rebooting ====
After rebooting, it is verified that the system has booted into Debian 13, is running the new kernel, and that there are no errors in the system log.
System and kernel version check – the ''VERSION_CODENAME'' field is expected to read //trixie// and the kernel version to be in the //6.12// series:
cat /etc/os-release
uname -r
System log check for errors and warnings (e.g. driver or hardware problems) – the output should be empty or contain no serious messages:
sudo dmesg --level=err,warn
Check that no packages remain un-upgraded after the upgrade – the list should be empty (with exception of kernel and kernel-modules. They can additionally be updated):
sudo apt update
sudo apt list --upgradable
===== Complete commands per product line =====
The following blocks contain the complete command sequence for each line for convenient copying. Before the final reboot, verify the system state as described in step 6.
==== Unipi Patron ====
sudo apt update && sudo apt upgrade -y
sudo reboot
sudo sed -i 's/bookworm/trixie/g' /etc/apt/sources.list /etc/apt/sources.list.d/debian-nonfree.list /etc/apt/sources.list.d/unipi.list
sudo apt update
sudo apt dist-upgrade
sudo rm /etc/apt/sources.list.d/unipi.list
sudo apt install unipi-kernel=6.12.101.0~trixie* unipi-kernel-modules=3.6~6.12.101.0~trixie*
# Verify the system state before rebooting (see step 6).
sudo reboot
==== Unipi Neuron ====
sudo apt update && sudo apt upgrade -y
sudo reboot
sudo rm /etc/apt/sources.list.d/raspberrypi.list
sudo sed -i 's/bookworm/trixie/g' /etc/apt/sources.list /etc/apt/sources.list.d/debian-nonfree.list /etc/apt/sources.list.d/unipi.list
sudo apt update
sudo apt dist-upgrade
sudo rm /etc/apt/sources.list.d/unipi.list
sudo apt install unipi-kernel=6.12.101.0~trixie* unipi-kernel-modules=3.6~6.12.101.0~trixie*
# Verify the system state before rebooting (see step 6).
sudo reboot
==== Unipi Gate ====
sudo apt update && sudo apt upgrade -y
sudo reboot
sudo sed -i 's/bookworm/trixie/g' /etc/apt/sources.list /etc/apt/sources.list.d/debian-nonfree.list /etc/apt/sources.list.d/unipi.list
sudo apt update
sudo apt dist-upgrade
sudo rm /etc/apt/sources.list.d/unipi.list
sudo apt install unipi-kernel=6.12.101.0~trixie*
# Verify the system state before rebooting (see step 6).
sudo reboot