# 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](https://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

```text
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

| Component | Minimum | Recommended |
|-----------|---------|-------------|
| Architecture | x86_64 | x86_64 |
| RAM | 2 GB | 8 GB+ |
| Storage | 20 GB | 64 GB+ (NVMe SSD) |
| Boot mode | UEFI | UEFI with Secure Boot |
| GPU | AMD, Intel, or NVIDIA | AMD (best out-of-box); NVIDIA via `-nvidia` variant |

### Choosing Your Variant

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

| Image | Desktop | Use Case |
|-------|---------|----------|
| `bazzite-gnome` | GNOME (Silverblue base) | Desktop/laptop with GNOME |
| `bazzite-kde` | KDE Plasma (Kinoite base) | Desktop/laptop with KDE |
| `bazzite-deck-gnome` | GNOME + Game Mode | Steam Deck / handhelds (GNOME desktop mode) |
| `bazzite-deck-kde` | KDE + Game Mode | Steam Deck / handhelds (KDE desktop mode) |
| `bazzite-gnome-nvidia` | GNOME + NVIDIA drivers | Desktop with NVIDIA GPU |
| `bazzite-kde-nvidia` | KDE + NVIDIA drivers | Desktop with NVIDIA GPU |

> [!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

```text
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:

```bash
rpm-ostree status
```

```text
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:

```bash
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:

| Profile | Use Case | sched_ext Mode |
|---------|----------|---------------|
| `balanced-bazzite` | Default — general desktop use | `auto` |
| `throughput-performance-bazzite` | Maximum gaming performance | `gaming` |
| `powersave-bazzite` | Battery life on laptops/handhelds | `powersave` |
| `balanced-battery-bazzite` | Balanced with battery awareness | — |
| `powersave-battery-bazzite` | Aggressive power saving | — |

Switch profiles:

```bash
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:

```bash
ujust update
```

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

### Firefox Configuration

Bazzite pre-configures Firefox for gaming:

| Setting | Value | Purpose |
|---------|-------|---------|
| `media.hardware-video-decoding.force-enabled` | `true` | Force hardware video decode |
| `widget.dmabuf.force-enabled` | `true` | NVIDIA: enable DMA-BUF |
| `widget.gtk.rounded-bottom-corners.enabled` | `true` | GNOME: rounded corners |
| `reader.parse-on-load.enabled` | `false` | Disable Reader mode auto-parse |
| `browser.ml.chat.enabled` | `false` | Disable AI chat features |

### 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:

```bash
ujust --list
```

Commands are organized by domain:

| File | Domain | Example Commands |
|------|--------|-----------------|
| `10-update.just` | System updates | Update system |
| `80-bazzite.just` | Core Bazzite tasks | General system tasks |
| `81-bazzite-fixes.just` | Bug fixes and workarounds | Fix common issues |
| `82-bazzite-apps.just` | Application management | Install/remove apps |
| `82-bazzite-sunshine.just` | Sunshine streaming | Setup/configure Sunshine |
| `82-bazzite-waydroid.just` | Android via Waydroid | Setup/manage Waydroid |
| `82-bazzite-beesd.just` | Btrfs deduplication | Manage beesd service |
| `83-bazzite-audio.just` | Audio fixes | Audio troubleshooting |
| `84-bazzite-virt.just` | Virtualization | VM/container setup |
| `85-bazzite-image.just` | Image management | Rebase, rollback |
| `86-bazzite-windows.just` | Windows dual-boot | Windows interop tasks |
| `87-bazzite-framegen.just` | Frame generation | Enable/disable FSR/AFMF |
| `88-bazzite-webapps.just` | Web applications | Install web apps |
| `89-bazzite-mesa-git.just` | Mesa Git drivers | Switch to mesa-git |
| `90-bazzite-picker.just` | Interactive picker | Menu-driven selection |
| `91-bazzite-decky.just` | Decky Loader | Install Decky plugins |
| `92-bazzite-verify.just` | Image verification | Verify signed image |

> [!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:

| Supported MIME Type | Example |
|---------------------|---------|
| `application/x-desktop` | `.desktop` files |
| `application/x-executable` | Linux binaries |
| `application/vnd.appimage` | AppImage files |
| `application/x-shellscript` | Shell scripts |
| `application/x-ms-dos-executable` | Windows `.exe` files |

> [!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:

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

### Waydroid (Android Apps)

Run Android applications natively via Waydroid:

```bash
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:

```bash
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

```bash
ujust update
```

This stages a new OS image. Reboot to apply.

### Switch to a Different Bazzite Variant

```bash
ujust rebase
```

Or manually:

```bash
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:

```bash
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

```bash
rpm-ostree rollback
```

Then reboot. The previous deployment is always available.

### Install Homebrew CLI Tools

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

```bash
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:

```bash
ujust setup-beesd
```

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

### Set Up Virtualization

```bash
ujust setup-virtualization
```

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

### Enable Frame Generation

```bash
ujust enable-framegen
```

### Serve Local Documentation

Bazzite includes a local documentation server:

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

```text
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

```text
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:
   ```bash
   rpm-ostree cleanup -p
   ```
2. Retry the update:
   ```bash
   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:
   ```bash
   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:
   ```bash
   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:
   ```bash
   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:

```bash
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:

```bash
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](https://docs.bazzite.gg)
- Universal Blue Discourse: accessible via the `discourse.desktop` launcher
- GitHub Issues: [github.com/ublue-os/bazzite/issues](https://github.com/ublue-os/bazzite/issues)

---

_Generated May 2026 from ublue-os/bazzite at 405c0ed. AI-generated documentation. The library is checked by sampling (three repositories so far); this guide was not individually reviewed. Verify against the project before relying on it. Unofficial; not affiliated with or reviewed by the project._