The Right Way to Upgrade Raspberry Pi OS (Major Versions)

A new major release of Raspberry Pi OS just dropped. If you’re still on an old and crusty installation, what’s the best way to get the latest and greatest? In today’s post, I’ll show you the ideal way to do a clean upgrade from Bookworm (or older) to Trixie.

The recommended way to upgrade Raspberry Pi OS to a new major release is to do a clean installation on a new SD card. The old SD card can be kept as a backup and used to move important files over to the new system after it’s up and running.

I’ll start by briefly mentioning a shortcut method first, but the point of this article is to show you the full steps to do an upgrade the right way.

If you’re new to Raspberry Pi or Linux, I’ve got something that can help you right away!
Download my free Linux commands cheat sheet – it’s a quick reference guide with all the essential commands you’ll need to get things done on your Raspberry Pi. Click here to get it for free!

Overview: What’s the Best Way to Upgrade Raspberry Pi OS?

Just so we’re clear: this guide isn’t about updating package versions for basic applications.
Today, we’re completing a major release upgrade, the whole shebang, moving from Raspberry Pi OS (bookworm or older) to Raspberry Pi OS (trixie).

A major release means foundational changes to the underlying parts of the operating system itself, which means new features, and the possibility of breaking your old setup.

What’s the best way to approach a release upgrade?

We’ve already covered a shortcut, which we sometimes call the kamikaze method, where you do an in-place upgrade of Raspberry Pi OS by swapping in new repositories and YOLO a global system update. But the truth is, this method isn’t recommended because it can lead to breakage.

The newest release of Raspberry Pi OS (Trixie) has a lot of overhauls—display server, audio, and network management—all of which make this method more risky than usual.

Let’s hear what the Raspberry Pi Foundation has to say on the matter:

As with all major version upgrades, we do not recommend or support attempting to upgrade a [running image]. […] The recommended method is to flash a clean copy…

Simon Long – Software Engineer / Raspberry Pi

This is what I’ll show you today: the smart way to do a clean upgrade.

These are the big picture steps involved:

• Back up important files.
• Do a clean install of Raspberry Pi OS.
• Restore your saved data.

Let’s go over each one in detail.

Step 1: Prepare Your Old System for Migration

In this section, you’ll determine which files to keep, back them up, and prep your Raspberry Pi to accept the newest Raspberry Pi OS.

Take an Inventory of What You Want to Keep

Before you open the hood and start tinkering with the engine, it’s best to figure out what you want to keep first. That way, you can protect yourself if something goes wrong with the upgrade. Here are my suggestions of where to look.

The Home Folder

Your user folder (e.g., /home/pat) contains all the personal files you might’ve stored over the years, like your pictures, manga, and 3D printing models.

But you might not realize that hidden folders reside here too.
You can see them all by running:
ls -hal

Folders like ~/.config/ and ~/.local/share/ contain application settings that you might need later.
And if there are other users on your system, they’ll also have separate folders in /home.

An easy approach here is to back up the entire /home folder.

Configuration Files in /etc

The /etc folder is quite important on most Linux systems: it contains configuration files for almost every application and service on your system, like a web server, SSH keys, cron jobs, and fstab mounting instructions.

This folder may contain tons of files, but they’re mostly text, so you’d be surprised at how little space they take up. To keep things simple, I take the same approach here as I do for /home.

Back up the entire /etc folder, and selectively restore what you need later.

Special Boot Files

The Raspberry Pi has two special boot files: config.txt and cmdline.txt.

On more recent installations, these files are located in the /boot/firmware folder.
If you’re on an older installation, these files are in /boot instead.

For example, your config.txt might contain overclock settings for retro-gaming.
If you’ve never modified these files, you probably won’t need to save them, but they’re tiny, so there’s no harm in backing them up just in case.

Installed Packages

When you move to a new system, you’ll want to reinstall your favorite applications.
But what if you don’t remember what you’ve installed?

Use the commands below to create text records of what to reinstall later:

• Record which packages have been installed by APT on your system:
  dpkg -l > my_packages.txt
  
  
• Record what services are running on your system:
  systemctl list-units --type=service --state=running > my_services.txt
  

Tip: Command lines can be a pain to memorize. I put the essential Linux commands on a printable cheat sheet so you don't have to keep googling them. You can grab the PDF here if you want to save some time.

How to Back Up Important Files

Now that you know what you want to keep, how do you make backups of these files?

There are many ways to skin a cat, so I’ll cover the simple ways first and link you to our guides if you need something more exotic.

Keep the Old SD Card as a Spare

The easiest backup method is to keep your old SD card intact. Then, use a separate SD card to install the new system. After you get your new system working, you can plug in your old SD card (with a USB card reader) and copy the files you need.

If you forgot something three months down the line, you can always pull that old SD card out of the drawer again. Fast and convenient.

Copy the Files to Another Storage Media

If you don’t have a spare SD card, you can always create a backup by copying the files from your Raspberry Pi to another storage medium.

For example, I like to use SFTP to copy the entire /home and /etc folders from my Pi to my PC. It saves me time from having to compress and decompress files.

Another way to do things would be to use the tar command to compress the folders you want to keep, and copy the archives onto a USB flash drive.

Or Use Advanced Backup Methods

If the backup methods above don’t work for you, we’ve covered other ways on our site. For example, you could create an image of your old system in case you ever need to restore it:
How to Create an Image of a Raspberry Pi SD Card? (Win/Linux/Mac).

For something more exotic, like backing up to an online cloud service, check out our guide:
5 Best Ways to Back Up Your Raspberry Pi (With Pros & Cons).

Step 2: Do a Clean Install of the Newest Raspberry Pi OS

All right, now that the old system is taken care of, it’s time to install the newest Raspberry Pi OS release from scratch.

Hint: It’s more convenient to do this with two SD cards. You can keep your old working system on one card as a backup, and install the new release on a separate card.

We already have multiple guides on how to do a clean install of Raspberry Pi OS.
You can choose from one of the following methods:

A) The standard way, with a USB SD card reader:
Install Raspberry Pi OS Trixie on Raspberry Pi (Illustrated Guide).

B) If you don’t have a spare monitor/keyboard:
How to Install a Headless Raspberry Pi (No Monitor).

C) If you don’t have another computer or SD card reader:
Network Boot Installation with Raspberry Pi.

Once you get your new system up, take the time to complete the basic configuration for Raspberry Pi OS: setting up users, network, installing updates, etc. After that’s all done, you’re ready to move on to the next step.

Step 3: Restore Your Saved Data

After doing a clean install of the newest Raspberry Pi OS release, how do you get your old stuff back? Here’s a tour of some common steps I recommend.

Reinstall Applications

Remember the list of packages that you recorded back in Step 1? Now it’s time to reinstall them.

You can install packages from either the GUI or the command line, whichever you’re more comfortable with. For more details, check out our guide: How to Easily Install Apps on Raspberry Pi OS? (5 Methods).

However, I don’t recommend reinstalling your entire old package list. Some dependencies might have changed in the new release. Instead, I would use it as a reference point to manually install new versions of anything you might’ve forgotten about.

Copy Over User Files

Remember the /home folder that you backed up earlier? You can copy some of it over to your new system. I would start with any personal files, like videos or notes—things you recognize that you put there yourself.

However, for hidden folders like ~/.config or ~/.local, I wouldn’t copy these over blindly. They can contain settings that conflict with the new app versions you’ve just installed. I would only copy from there if I had tons of custom settings for a specific app that I really needed to recreate.

For most applications, I normally just go with the new default settings and work from there.

Restore Configuration Files

Remember the /etc folder that you backed up earlier? You can copy some of these over, too. I recommend doing this selectively, only copying configuration files for services that you know you’ve modified heavily.

For instance:

• /etc/ssh
• /etc/apache2
• /etc/ts.conf

For the rest, I would accept the new files that were installed in /etc by default. Only when I realize that some service or program isn’t working the way it used to, then I would hunt for the old configuration file in my backup and restore that specific one.

Test Services

Remember the list of services that you saved earlier?
Here’s how to get those services up and running again:

• Reinstall the package for a service.
  (For instance: sudo apt install apache2)
• Copy its configuration files over, often found in your old /etc folder.
  (For instance, Pi-hole settings might have been stored in /etc/pihole)
• Activate the service and enable autostart:
  sudo systemctl start <service>
sudo systemctl enable <service>
  (For more details, check out our guide on How To Use ‘systemctl’.)
• Run some tests to see if your service is working as intended.

It’s easier if you do these steps one service at a time. For example, install and check that your web server is working before moving on. Then, check whether your Pi-Hole is adblocking correctly. And so on.

Congrats, that should cover most of the steps you need to upgrade to a new release! If you’re an advanced user, check out the next section for more tips and tricks.

Tips & Tricks for Upgrading Between Major Releases

The truth is that every system is different, so I couldn’t cover every little situation in the steps above. In this section, I’ll cover a few additional tips and tricks that may help you with backup and restoration.

Cron Jobs

If you’ve set up automated tasks or scripts (cron jobs), you’ll have to restore these manually.

On your old system, I recommend viewing and copying/pasting your crons from here:
crontab -e
sudo crontab -e

If you can’t access a running system, then you’ll have to copy the files over instead.
You can hunt for them in the following locations on your old installation:

• User jobs: /var/spool/cron/crontabs/
• System jobs: /etc/crontab and /etc/cron.d/

Web Server

If you host a website, you’ll want to ensure you copy it over from your old system. By convention, you likely stored the site files in the /var/www/ or /var/www/html folder.

Here are the general steps to restore your website:

• Copy the site files over to the same folders on your new system.
• Copy the old configuration files for your chosen web server over to your new system.
  (For Apache / nginx / Caddy, for instance, they’re often found in the /etc folder.)
• Start and enable the web server on your new installation.
• Test if your website is reachable.

If you forgot how you set things up, check out our guide to jog your memory: Host a Website at Home with Raspberry Pi.

Database Files

If you store important info in databases, then you’ll want to move it over to your new system as well. The best way to do this is to use the database application’s export feature.

First, export the databases from your old system:

• Launch the database application.
• Use the export feature to export each database one-by-one.
• This operation will create database backups, export.sql, for instance.

Then, restore the databases on your new system:

• Copy the exported files over to your new system.
• Launch the database application.
• Use the import feature on the selected files to restore each database one-by-one.

The specific steps might slightly differ depending on the database you’re using on your Raspberry Pi (MySQL or MongoDB, for instance).

Virtual Environments

For the coders out there, you may have cherished Python virtual environments that you want to recreate. But don’t zip up the entire venv folder, as that probably won’t restore properly. Instead, export virtual environments from your old system and restore them on your new system.

First, export the virtual environment from your old system:

• Activate the virtual environment:
  source /path/to/venv/bin/activate
• Export the environment settings:
  pip freeze > requirements.txt

Then, restore the virtual environment on your new system:

• Create and activate the virtual environment:
  python3 -m venv venv
source venv/bin/activate
• Update to the newest version of pip, just in case:
  pip install --upgrade pip
• Restore the environment:
  pip install -r requirements.txt

Containers

Restoring containers, from Docker or Podman, will heavily depend on how you set it up originally.

For example, I use Docker Compose files, which I store in my ~/containers folder. So I simply copied that entire folder over from my old system to my new one, and let Docker pull and recreate everything from my configuration. I don’t need to manually restore every file from my old setup, as this portability is why I like to run containers in the first place.

Recommended: copy the container configurations over, and let Docker/Podman do the rest.

But what if you had custom settings inside the container that you really needed to keep?
In that case, read the container’s configuration file (e.g., YAML) and look for the ‘volumes’ section.

The paths listed to the left of the colon (:) tell you where these files are on your local system.
You can then copy those folders onto your new system, if needed.

That finishes our tutorial for today. I hope I’ve demystified the process and made you more confident in upgrading your Raspberry Pi cleanly.

Not getting the same result?

Even when you follow every step, small differences in OS version, hardware or config can change the outcome. Instead of wasting time guessing, get help from people who have already fixed the same kind of issue.

Ask your question now →

🔒 No risk. Cancel anytime.

• Get help on your exact issue
• Access step-by-step videos for tricky setups
• Browse the website without ads