Skip to content

Rebase Guide

Docker's OCI Icon|200x200, 100%

What is Rebasing?

Warning

Rebasing between different desktop environments (e.g. KDE Plasma to GNOME) may cause issues and is unsupported.

Rebasing allows users to switch to a different image without having to reinstall and lose personal files and application data.

It is recommended to use the Bazzite Rollback Helper utility.

Rebase Scenarios

  • Rebase to specific images of older builds within the last 90 days if issues are occurring on the newest build of Bazzite.
  • Rebase to other Fedora Atomic Desktop images including other Bazzite images.
    • Do not rebase between different desktop environments.

How do I swap between Bazzite (and other Fedora Atomic Desktop) images?

See what channel or build you are on by entering this command in a host terminal:

rpm-ostree status

Check under "Deployments:" and the output should be similar to:

 ● ostree-image-signed:docker://ghcr.io/ublue-os/[*image*]:[*channel*]

Switch to another Bazzite variant by entering the command for each specific image.

Open the terminal and enter:

rpm-ostree rebase <image>

Example:

rpm-ostree rebase ostree-image-signed:docker://ghcr.io/ublue-os/bazzite-deck:stable

For rebasing to the generic KDE Plasma version of the Handheld & HTPC image.

Warning

Rebasing between different desktop environments (e.g. KDE Plasma to GNOME) may cause issues and is unsupported.

How do I change the Bazzite's update branch? (Stable, Testing, and Unstable)

There are 3 branches you can switch to:

  • Stable (:stable)
    • Default branch that's used in normal Bazzite installations
  • Testing (:testing)
    • Get a sneak peak of future Bazzite builds before release
    • Bugs may frequently appear
    • Encouraged to rebase back to :stable after testing a major release
      • It can be behind on certain updates for a long time
  • Unstable (:unstable) (DO NOT USE)
    • Not recommended
    • Testing playground for developers/contributors
    • Can be several months behind compared to both :stable and :testing updates when not in use
    • Intended for testing desktop environments and other radically changed functionality to Bazzite for the future

Bazzite-Deck images can switch branches in Settings > System > OS Update Channel in Steam Gaming Mode.

If you enabled advanced update channel, then additional options will appear. The options map as the following:

Stable (:stable)
Release Candidate (:testing)
Beta (:testing)
Beta Candidate (:unstable)
Main (:unstable)

For Desktop images, replacing :stable with :testing or :unstable to the end of the rebase command for your Bazzite image allows you to switch to the experimental branches (which may have frequent bugs.)

Example:

rpm-ostree rebase ostree-image-signed:docker://ghcr.io/ublue-os/bazzite:testing

For the testing branch on the generic AMD/Intel Desktop image.

Can I stay on a specific Fedora release?

Warning

You will have to rebase back to :stable once you want to upgrade to the next Fedora version.

Important

Switching to older Fedora versions will not bring new updates until you upgrade back to :stable and this also means no security updates for the time being.

Yes, but only if that version of Fedora is still currently supported upstream.

  • Replace :stable with the supported version of Fedora you would like to stay on.
  • Fedora Rawhide is not supported.

Rebasing to older builds

Attention

You will have to rebase back to :stable once you want to upgrade to the newest release.

  • Like rolling back to the previous Bazzite deployment, users can also rebase to a specific Bazzite builds that was were built within the last 90 days.
  • All of your userdata will remain intact, but like how the warning indicates above, you will have to rebase manually back to :stable to update the system to receive the newest build.

View the list of available stable builds by entering:

skopeo list-tags docker://ghcr.io/ublue-os/bazzite | grep -- "stable-" | sort -rV

Rebasing to a specific build requires users to open a host terminal and enter:

rpm-ostree rebase ostree-image-signed:docker://ghcr.io/ublue-os/IMAGE-NAME:VERSION-YEARMONTHDAY

Example:

rpm-ostree rebase ostree-image-signed:docker://ghcr.io/ublue-os/bazzite-deck:39-20240113

For the Jan. 13th 2024 bazzite-deck (Fedora 39) build.

(Please note that this build is no longer available since it is past the 90 day limit and is only used as an example for this documentation.)

← Back to Updates, Rollback, and Rebasing Guide