Bazzite User Guide

1. Quick Start

Bazzite is a gaming-focused Linux desktop operating system built on Fedora Atomic (Universal Blue). It ships as an immutable OCI container image with pre-configured Steam, Lutris, MangoHud, Gamescope, and hundreds of hardware-specific optimizations for devices ranging from the Steam Deck to ASUS ROG Ally, GPD Win, Lenovo Legion Go, and standard desktop PCs.

Key features:

• Immutable, atomic OS updates via bootc/rpm-ostree — rollback to any previous version instantly
• Pre-installed Steam, Lutris, and gaming infrastructure (Gamescope, MangoHud, umu-launcher)
• Handheld/HTPC Game Mode with Steam Big Picture as the shell
• Desktop Mode with GNOME or KDE Plasma (your choice at install time)
• NVIDIA driver support baked into dedicated image variants
• Hardware-tuned audio profiles (WirePlumber/PipeWire) for dozens of devices
• Waydroid (Android app) support, Sunshine (game streaming) support
• Flatpak-first application model with Flathub pre-configured
• Secure Boot support with automatic MOK key enrollment
• ujust command system for common administrative tasks

Prerequisites: x86_64 PC or supported handheld, 2 GB+ RAM, 20 GB+ storage, UEFI boot.

Get running in 2 minutes:

1. Download the ISO for your variant from bazzite.gg
2. Flash it to a USB drive with Ventoy, Rufus, or dd
3. Boot from the USB and follow the Anaconda installer
4. Reboot — you are running Bazzite

Bazzite release 42 (Forty Two)

Tip

Choose the Deck ISO variant if installing on a Steam Deck or handheld gaming PC — it boots directly into Steam Game Mode.

What to try next:

• Open the terminal and run ujust to see available system commands
• Install apps from Flathub via your desktop's software center
• See the Configuration section for performance tuning profiles

2. Installation

System Requirements

Choosing Your Variant

Bazzite ships multiple image variants. Pick based on your hardware and desktop preference:

Important

If you have an NVIDIA GPU, you must use a -nvidia variant. The standard images do not include proprietary NVIDIA drivers.

Installation from ISO

1. Download the ISO matching your variant
2. Write it to a USB drive (minimum 8 GB)
3. Boot from USB — select Launch Bazzite Installer at the GRUB menu
4. The Anaconda installer launches — select language, timezone, disk, and user account
5. Click Begin Installation and wait for completion
6. Remove USB and reboot

Launch Bazzite Installer
Launch Bazzite Installer (Basic Graphics Mode)

Warning

If you have a Windows BitLocker partition, the installer will detect it and warn you. Either disconnect the Windows drive, disable BitLocker in Windows, or delete the partition before proceeding.

Deck variant default user: On deck images, the installer pre-creates a user bazzite with password bazzite. Change this immediately after first boot.

Secure Boot Enrollment

On UEFI systems with Secure Boot enabled, the installer automatically enrolls the Universal Blue MOK (Machine Owner Key). After the first reboot:

1. The MOK Manager screen appears
2. Select Enroll MOK
3. Enter the enrollment password: universalblue
4. Confirm and reboot

Note

Steam Deck hardware does not support Secure Boot. The installer skips key enrollment automatically on Jupiter/Galileo hardware.

Post-Install Verification

After first boot, verify your installation:

rpm-ostree status

State: idle
Deployments:
● ostree-image-signed:docker://ghcr.io/ublue-os/bazzite-gnome:42
                   Digest: sha256:abc123...
                  Version: 42.20260507 (2026-05-07T00:00:00Z)

Rebasing (Switching Variants)

Already running Fedora Atomic or another Universal Blue image? Rebase directly:

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

Caution

Rebasing replaces your entire OS layer. Back up personal data first. User files in /home are preserved, but layered packages may conflict.

Install Troubleshooting

Problem: Installer shows black screen Boot with Basic Graphics Mode from the GRUB menu (adds nomodeset kernel parameter).

Problem: "Unencapsulating base: rename pending: renameat: File exists" Known issue (#4204). Retry the update; if persistent, run rpm-ostree cleanup -p then try again.

Problem: No display output after install on NVIDIA Ensure you installed the -nvidia variant. If you accidentally used the standard image, rebase to the NVIDIA variant.

Problem: Anaconda crashes during partitioning Open GParted (pre-installed on the live ISO) and manually partition before running the installer.

3. Configuration

Performance Tuning Profiles

Bazzite includes custom tuned profiles optimized for different workloads:

Switch profiles:

sudo tuned-adm profile throughput-performance-bazzite

Tip

The throughput-performance-bazzite profile activates scxctl switch -m gaming for the sched_ext scheduler — measurably improving frame pacing in CPU-bound games.

System Updates

Bazzite updates atomically. The system downloads the new image, stages it, and applies it on the next reboot:

ujust update

Or let the automatic timer handle it — uupd.timer runs periodic checks.

Firefox Configuration

Bazzite pre-configures Firefox for gaming:

Shell Enhancements

Bazzite enhances the terminal out of the box:

• eza replaces ls with icons and directory-first sorting (ll, ls, l1, l.)
• ugrep replaces grep with faster ug (grep, egrep, fgrep)
• atuin provides shell history search
• zoxide provides smart cd replacement
• fastfetch replaces neofetch with Bazzite branding

Note

These aliases are defined in /usr/share/bazzite-cli/bling.sh and sourced via profile.d scripts. They activate in both bash and zsh.

Distrobox (Mutable Containers)

Bazzite pre-configures Distrobox for running mutable Linux environments inside the immutable OS. Default container configuration is at /etc/distrobox/distrobox.ini.

For full configuration reference, see the Admin Guide.

4. Core Usage

ujust Command System

ujust is Bazzite's primary interface for system management tasks. It wraps the just command runner with a library of pre-built recipes:

ujust --list

Commands are organized by domain:

Tip

Run ujust with no arguments to get an interactive picker that lets you browse and select from all available commands.

Desktop Mode vs. Game Mode (Deck Variants)

On Deck variants, Bazzite boots into Steam Game Mode by default — Steam Big Picture runs as the compositor via Gamescope. To switch:

• Game Mode → Desktop: Use the Steam menu → Switch to Desktop Mode
• Desktop → Game Mode: Log out and select the Game Mode session, or use ujust

Warning

After system updates, "Switch to Desktop Mode" may temporarily disappear from the Steam menu (#4625). Restarting Steam or rebooting resolves this.

Steam and Game Launchers

Steam is pre-installed. Additional launchers are available:

• Lutris — manages Wine/Proton games, GOG, Epic, etc.
• umu-launcher — Valve's unified game launcher for Proton outside Steam
• MangoHud — in-game performance overlay (FPS, CPU/GPU usage, frame timing)
• Gamescope — Valve's micro-compositor for per-game resolution/refresh rate control

Adding Non-Steam Applications

On GNOME, the Nautilus file manager provides an Add to Steam right-click menu item for supported file types:

Note

The file must be executable (except .exe files). Non-executable files will not show the menu item.

Flatpak Applications

Bazzite uses Flatpak as the primary application delivery mechanism. Flathub is pre-configured:

flatpak install flathub org.mozilla.firefox
flatpak list
flatpak update

Waydroid (Android Apps)

Run Android applications natively via Waydroid:

ujust setup-waydroid

Waydroid container management scripts are provided at /usr/libexec/waydroid-container-{start,stop,restart}.

Sunshine (Game Streaming)

Stream your desktop to Moonlight clients:

ujust setup-sunshine

The systemd user services sunshine.service and sunshine-kms.service are pre-configured with drop-in overrides for GNOME compatibility.

5. Common Tasks

Update Your System

ujust update

This stages a new OS image. Reboot to apply.

Switch to a Different Bazzite Variant

ujust rebase

Or manually:

rpm-ostree rebase ostree-image-signed:docker://ghcr.io/ublue-os/bazzite-kde-nvidia:42

Verify Image Signature

If you see the security warning about an unverified image on login:

ujust verify-image

Warning

Running an unverified image means automatic updates and container signature verification are disabled. Fix this promptly.

Roll Back to Previous Version

rpm-ostree rollback

Then reboot. The previous deployment is always available.

Install Homebrew CLI Tools

Bazzite integrates Homebrew (Linuxbrew) for user-space CLI tools:

brew install fzf ripgrep bat

A Brewfile at /usr/share/ublue-os/homebrew/bazzite-cli.Brewfile lists recommended tools.

Enable Btrfs Deduplication

If your filesystem is Btrfs:

ujust setup-beesd

The beesd@.service timer runs deduplication periodically (configured with custom timeout overrides).

Set Up Virtualization

ujust setup-virtualization

The bazzite-libvirtd-setup.service handles libvirt configuration. An incus-workaround.service is included for Incus container compatibility.

Enable Frame Generation

ujust enable-framegen

Serve Local Documentation

Bazzite includes a local documentation server:

/usr/share/ublue-os/docs/serve.sh

Serving HTTP on 127.0.0.1 port 1290 ...

This opens your browser to http://127.0.0.1:1290 with offline documentation.

6. Troubleshooting

Diagnostic Decision Tree

System won't boot?
├── Black screen → Try Basic Graphics Mode (nomodeset)
├── Kernel panic → Roll back: select previous deployment in GRUB
└── Stuck at login → Check if Game Mode session is available

Network issues?
├── WiFi drops after sleep → Known issue (#2473), reboot as workaround
├── uupd fails on VPN → Known issue (#4592), disconnect VPN for updates
└── No network at all → Check NetworkManager: systemctl status NetworkManager

Audio problems?
├── No sound on ROG Ally X → Audio regression (#4366), check for updates
├── Wrong output device → WirePlumber hardware profiles may need updating
└── Crackling/popping → Adjust ALSA headroom in WirePlumber config

Gaming issues?
├── Steam won't start (#4616) → Kill existing Steam processes, restart
├── 32-bit ELFCLASS errors (#2908) → Fixed: libextest.so preload issue resolved
└── Game Mode exiting (#4624) → KDE services may not stop cleanly; rebooting cleans up

Error: ujust update fails with "rename pending: renameat: File exists"

Cause: Stale pending deployment from a previous interrupted update (#4204).

Solution:

1. Clean pending deployments:

   rpm-ostree cleanup -p
   

2. Retry the update:

   ujust update
   

Prevention: Avoid interrupting updates. Let them complete before rebooting.

Error: Ethernet and WiFi stop working after a while

Cause: Network stack instability under certain hardware configurations (#2473, 62 comments).

Solution:

1. Reboot as immediate fix
2. Check for kernel/firmware updates
3. Try switching between NetworkManager backends:

   nmcli general status
   

Prevention: Keep system updated; hardware-specific fixes are included in newer images.

Error: Fans won't turn off in sleep mode

Cause: Power management regression on certain handhelds (#4593).

Solution:

1. Check if jupiter-fan-control is running:

   systemctl status jupiter-fan-control
   

2. Update to latest image — fan control patches are delivered via image updates

Error: Random black screen during use

Cause: GPU driver or compositor issue (#4621).

Solution:

1. Switch to a TTY with Ctrl+Alt+F3
2. Restart the display manager:

   sudo systemctl restart display-manager
   

3. If persistent, check GPU reset rules in /usr/lib/udev/rules.d/80-gpu-reset.rules

Error: Internal drive listed twice on HTPC/Deck build

Cause: Duplicate device entries in automount configuration (#1098).

Solution: Check udev rules and SD card rescan configuration. This is a cosmetic issue that does not affect functionality.

Caution

Never manually edit files under /usr on an immutable system — your changes will be lost on the next update. Use /etc overrides or ujust commands instead.

7. FAQ

Q: What is the difference between Bazzite and regular Fedora?

Bazzite is built on Fedora Atomic (Silverblue/Kinoite) with gaming-specific packages, drivers, and configurations pre-installed. The OS is immutable — updates replace the entire system image atomically, with instant rollback capability. Regular Fedora uses traditional package management where individual packages are upgraded in place.

Q: Can I install RPM packages on Bazzite?

You can layer packages with rpm-ostree install <package>, but this is discouraged for most software. Use Flatpak for GUI apps and Homebrew or Distrobox for CLI tools. Layered packages increase update time and can cause conflicts.

Tip

The dnf command is aliased to a wrapper that opens documentation. pacman, apt, and yum are also aliased to this wrapper to help users from other distributions find the right approach.

Q: How do I switch between GNOME and KDE?

Rebase to the other variant:

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

This replaces your desktop environment while preserving /home.

Q: Does Bazzite support Secure Boot?

Yes. The installer enrolls a Machine Owner Key (MOK) automatically. The enrollment password is universalblue. Steam Deck hardware is an exception — it does not support Secure Boot.

Q: How do I check if my image is signed/verified?

A login warning appears if you are running an unverified image. Fix it with:

ujust verify-image

The verification script at /etc/profile.d/verify_motd.sh checks for the ostree-unverified-registry tag in your deployment.

Q: What handhelds are supported?

Bazzite includes hardware-specific configurations for:

• Valve Steam Deck (Jupiter/Galileo)
• ASUS ROG Ally / ROG Ally X
• Lenovo Legion Go
• GPD Win 4 / GPD Win Mini
• MSI Claw / Claw 7 AI+ / Claw 8 AI+
• Framework Desktop (AMD Ryzen AI Max 300 series)

Hardware support includes WirePlumber audio profiles, PipeWire filter chains, display colorimetry profiles, udev rules, and custom EDID firmware.

Q: How do I access the Bazzite announcements system?

System announcements appear as notifications on login. They are JSON files in /usr/share/ublue-os/announcements/ and can be conditionally triggered based on image version.

Q: Where can I get help?

• Bazzite documentation: docs.bazzite.gg
• Universal Blue Discourse: accessible via the discourse.desktop launcher
• GitHub Issues: github.com/ublue-os/bazzite/issues