bazzite Documentation

Bazzite makes gaming and everyday use smoother and simpler across desktop PCs, handhelds, tablets, and home theater PCs.

8,896 stars Just 1 file · ~7,996 tokens #desktop#fedora-kinoite#fedora-linux#fedora-silverblue#gaming#htpc#legiongo#oci-image
RAW Doc

Docker & Self-Hosted Deployment Verified OCI

Deploy bazzite on any server, homelab, or cloud container platform.

1-Click Terminal Command
bash (docker run) 
docker run -d --name bazzite --restart always ublue-os/bazzite:latest

1. Project Overview & Quickstart (ublue-os/bazzite)

[🇺🇸](https://github.com/ublue-os/bazzite/blob/main/README.md) [🇪🇸](https://github.com/ublue-os/bazzite/blob/main/README-SPA.md) [🇮🇩](https://github.com/ublue-os/bazzite/blob/main/README-ID.md) [🇨🇳](https://github.com/ublue-os/bazzite/blob/main/README-zh-cn.md) [🇫🇷](https://github.com/ublue-os/bazzite/blob/main/README-FR.md) [🇧🇷](https://github.com/ublue-os/bazzite/blob/main/README-BR.md) [🇳🇱](https://github.com/ublue-os/bazzite/blob/main/README-NL.md) [🇷🇺](https://github.com/ublue-os/bazzite/blob/main/README-RU.md) [🇩🇪](https://github.com/ublue-os/bazzite/blob/main/README-DE.md) [🇹🇼](https://github.com/ublue-os/bazzite/blob/main/README-ZH-TW.md) [🇹🇷](https://github.com/ublue-os/bazzite/blob/main/README-TR.md)

Table of Contents

About & Features

Please see our website for a newcomer-friendly explanation of Bazzite. This readme will cover everything in-depth.

Bazzite is a custom Fedora Atomic image built with cloud native technology that brings the best of Linux gaming to all of your devices - including your favorite handheld.

Bazzite is built from ublue-os/main using Fedora technology, which means expanded hardware support and built in drivers are included. Additionally, Bazzite adds the following features:

  • Uses the OGC kernel
  • HDR and VRR available by default.
  • Full hardware accelerated codec support for H264 decoding.
  • xone driver for Xbox controllers.
  • Full support for DisplayLink.
  • vkBasalt, MangoHud, and OBS VkCapture installed and available by default.
  • ROM Properties Page shell extension included.
  • Distrobox preinstalled.
  • Automated bees service for reducing the disk space used by wine prefix contents.
  • Support for HDMI CEC.
  • Input Remapper preinstalled and enabled. (Available but default-disabled on the Deck variant, may be enabled with ujust restore-input-remapper)
  • Bazzite Portal provides an easy way to install numerous applications( and tweaks, including installing LACT and IDEs over Brew. It additionally provides easy buttons to update, rebase and even reset the system image to defaults.
  • Waydroid preinstalled for running Android apps. Set it up with this quick guide.
  • Manage applications using Flatseal, Warehouse, and Gear Lever.
  • OpenRazer drivers built in, Select OpenRazer in Bazzite Portal or run ujust install-openrazer in a terminal to begin using it.
  • OpenTabletDriver udev rules built in, with the full software suite installable via Bazzite Portal or by running ujust install-opentabletdriver in a terminal.
  • Webapp Manager is available for creating applications from websites for a variety of browsers, including Firefox.

Desktop

Common variant available as bazzite, suitable for desktop computers.

  • Automatic updates for the OS, Flatpaks, and more - powered by uupd and topgrade.

[!IMPORTANT]
ISOs can be downloaded from our website, and a helpful install guide can be found here.

Rebase from an existing upstream Fedora Atomic to this image if you want Open Source GPU Drivers:
(Please note: Mesa's Open Source option for NVIDIA GPUs, NVK is still prone to errors at the time of writing, for any issues relating to NVK please submit a report with Mesa, not Ublue/Bazzite)

bash
rpm-ostree rebase ostree-unverified-registry:ghcr.io/ublue-os/bazzite:stable

or for devices with Nvidia GPUs wanting the NVIDIA Proprietary Drivers:

bash
rpm-ostree rebase ostree-unverified-registry:ghcr.io/ublue-os/bazzite-nvidia:stable

For users with Secure Boot enabled: Follow our secure boot documentation prior to rebasing.

Steam Deck/Home Theater PCs (HTPCs)

Variant designed for usage as an alternative to SteamOS on the Steam Deck, and for a console-like experience on HTPCs, available as bazzite-deck:

  • Directly boots to Game mode matching SteamOS's behavior.
  • Automatic bees greatly trims the size of compatdata.
  • Latest version of Mesa creates smaller shader caches and does not require them to prevent stutter.
  • Able to be booted even if the drive is full.
  • Support for every language supported by upstream Fedora.
  • Uses Wayland on the desktop with support for Steam input.
  • Features ported versions of most SteamOS packages, including drivers, firmware updaters, and fan controllers from the evlaV repository.
  • Patched Mesa for proper framerate control from Gamescope.
  • Comes with patches from SteamOS BTRFS for full BTRFS support for the SD card by default.
  • Ships with a ported copy of SDGyroDSU, enabled by default.
  • Option to install Decky Loader, EmuDeck, RetroDECK, and ProtonUp-Qt, among numerous other useful packages on installation.
  • Custom update system allows for the OS, Flatpaks, and more to be updated directly from the Game mode UI powered by uupd and topgrade.
  • Built in support for Windows dual-boot thanks to Fedora's installation of GRUB being left intact.
  • Update break something? Easily roll back to the previous version of Bazzite thanks to rpm-ostree's rollback functionality. You can even select previous images at boot.
  • Steam and Lutris preinstalled on the image as layered packages.
  • Uses ZRAM(4GB) with the LZ4 compression algorithm by default.
  • LAVD and BORE CPU Schedulers for smooth and responsive gameplay.
  • Kyber I/O scheduler to prevent I/O starvation when installing games or during background duperemove process.
  • Applies SteamOS's kernel parameters.
  • Color calibrated display profiles for matte and reflective Steam Deck screens included.
  • Default-disabled power-user features, including:
    • Service for low-risk undervolting of the Steam Deck as well as AMD Framework Laptops via RyzenAdj and Ryzen SMU, see ryzenadj.service and /etc/default/ryzenadj.
    • Built in support for display overclocking. For example, add CUSTOM_REFRESH_RATES=30-68 to /etc/environment. Minimum and maximum refresh rates differ per handheld!
    • 32GB RAM mod your Steam Deck? Enjoy double the maximum VRAM amount, automatically applied. (Can you share your soldering skills?)
  • Steam Deck hardware-specific services can be disabled by running ujust disable-bios-updates and ujust disable-firmware-updates in the terminal. These are automatically disabled on non-Deck hardware, and on Decks with DeckHD displays or 32GB RAM mods.
  • More information can be found here on the Bazzite Steam Deck images.

[!IMPORTANT]
ISOs can be downloaded from our website, and a helpful install guide can be found here.

Rebase from an existing upstream Fedora Atomic to this image:

bash
rpm-ostree rebase ostree-unverified-registry:ghcr.io/ublue-os/bazzite-deck:stable

Alternative Handhelds

Please refer to our Handheld Wiki for required setting changes and Decky Loader plugins for Steam Gaming Mode on your specific Handheld.

GNOME

Builds with the GNOME desktop environment are available in both desktop and deck flavors. These builds come with the following additional features:

[!IMPORTANT]
ISOs can be downloaded from our website, and a helpful install guide can be found here.

Rebase from an existing upstream Fedora Atomic to this image:

bash
rpm-ostree rebase ostree-unverified-registry:ghcr.io/ublue-os/bazzite-gnome:stable

To rebase an existing ostree system to a Desktop Environment with the Proprietary NVIDIA Drivers release:

bash
rpm-ostree rebase ostree-unverified-registry:ghcr.io/ublue-os/bazzite-gnome-nvidia:stable

To rebase an existing ostree system to the Steam Deck/HTPC release:

bash
rpm-ostree rebase ostree-unverified-registry:ghcr.io/ublue-os/bazzite-deck-gnome:stable

For users with Secure Boot enabled: Follow our secure boot documentation prior to rebasing.

Features from Upstream

Universal Blue

  • Proprietary Nvidia drivers pre-installed. (Only for Nvidia images)
  • Flathub is enabled by default.
  • ujust commands for convenience.
  • Multi-media codecs out of the box.
  • Rollback Bazzite from any build within the last 90 days.

Features from Fedora Linux (Kinoite & Silverblue)

  • A rock solid and stable base.
  • System packages stay relatively up to date.
  • Can layer Fedora packages to the image without losing them between updates.
  • Security focused with SELinux preinstalled and configured out of the box.
  • The ability to rebase to different Fedora Atomic images, if desired, without losing user data.
  • Printing support thanks to CUPS being preinstalled.

Why

Bazzite started as a project to resolve some of the issues that plague SteamOS, mainly out of date packages (despite an Arch base) and the lack of a functional package manager.

Despite this project also being image-based, you are able to install any Fedora package straight from the command line. These packages will persist across updates (So go ahead and install that obscure VPN software you spent an hour trying to get working in SteamOS). Additionally, Bazzite is updated multiple times a week with packages from upstream Fedora, giving you the best possible performance and latest features - all on a stable base.

Bazzite ships with the latest Linux kernel and SELinux enabled by default with full support for secure boot (Run ujust enroll-secure-boot-key and enter the password universalblue if prompted to enroll our key) and disk encryption, making this a sensible solution for general computing. (Yes, you can print from Bazzite)

Read the FAQ for details on what makes Bazzite stand out from other Linux based operating systems.

Showcase

Documentation

View additional documentation surrounding the project.

Verification

These images are signed with sigstore's cosign. You can verify the signature by downloading the cosign.pub key from this repo and running the following command:

bash
cosign verify --key cosign.pub ghcr.io/ublue-os/bazzite

Secure Boot

[!WARNING]
Steam Deck Users: The Steam Deck does not come with secure boot enabled and does not ship with any keys enrolled by default. Do not enable this unless you absolutely know what you're doing.

Secure boot is supported with our custom key. The pub key can be found in the root of this repository here.
If you'd like to enroll this key prior to installation or rebase, download the key and run the following:

bash
sudo mokutil --timeout -1
sudo mokutil --import secure_boot.der

For users already on a Universal Blue image, you may instead run ujust enroll-secure-boot-key.

If asked for a password, use universalblue.

Contributor Metrics

Star History

Special Thanks

Bazzite is a community effort and wouldn't exist without everyone's support. Below are some of the people who've helped us along the way:

  • amelia.svg - For creating our logo and overall branding.
  • SuperRiderTH - For creating our Steam game mode startup video.
  • evlaV - For making Valve's code available and for being this person.
  • ChimeraOS - For gamescope-session and for valuable support along the way.
  • Jovian-NixOS - For supporting us with technical issues and for creating a similar project. Seriously, go check it out. It's our Nix-based cousin.
  • sentry - For assistance with needed kernel patches and for creating the kernel-fsync repo.
  • nicknamenamenick - For being the MVP nearly single-handedly upkeeping our documentation and support literature, and countless cases of helping users.
  • Steam Deck Homebrew - For choosing to support distributions other than SteamOS despite the extra work, and a special thanks to PartyWumpus for getting Decky Loader working with SELinux for us.
  • cyrv6737 - For the initial inspiration and the base that became bazzite-arch.

Build Your Own

Bazzite is built entirely via GitHub Actions. Creating your own custom version of it is as easy as forking this repository, adding a private signing key, and enabling the fork's GitHub Actions. Running the Build Bazzite workflow will then generate custom images for all variants of Bazzite.

If you only want to generate images for the variants of Bazzite you are using, edit .github/workflows/build.yml to comment out the variants you do not wish to build in the push-ghcr job's strategy's matrix list.

We also ship a config for the popular pull app if you'd like to keep your fork in sync with upstream. Enable this app on your repo to keep track of Bazzite changes while also making your own modifications.

How to Sign Your Images

  1. First, familiarize yourself with keeping secrets on GitHub.
  2. Generate a new key pair with Cosign (cosign generate-key-pair). This key pair must have no signature.
  3. Replace the cosign.pub file in your public repo with the one you generated - you and your users will need it to check the signatures.
  4. Add the private key (stored as text inside the cosign.key file) as a Repository Secret in the fork's settings page, in the Settings -> Secrets and variables -> Actions menu. Name the secret SIGNING_SECRET.

Join The Community

You can find us on the Bazzite Discord View the archive of support threads without an account.

2. Official Technical Reference & Guides (ublue-os/website)

File: README.md

Universal Blue Website

This is the MkDocs repository that hosts the website for Universal Blue.

Developing

You will need Python version 3.10 or higher and Poetry.

  1. Setup project dependencies poetry install
  2. Run the local development server poetry run mkdocs serve
  3. Open a browser to localhost:8000. This will auto-reload on file changes

If you have access to mkdocs-material-insiders, run the following to install it:

sh
poetry run pip install git+ssh://[email protected]/squidfunk/mkdocs-material-insiders.git@29bd630bf94c3a3c0eef8118cf1289c226252636

Then use

sh
poetry run mkdocs serve -f mkdocs.insiders.yml

Contributing

  1. Create a fork of this repository
  2. Create a new branch for your contribution git checkout -b my-new-branch
  3. Add your contributions! Make changes, use poetry run mkdocs serve to validate those changes
  4. Commit and push your changes to your branch
  5. Open a pull request to have it reviewed

Editing the Image list

Edit .github/ublue-scan.yml to add images to the ignore list.
Use this for images that you don't want to be shown on ublue.it/images.
Typically we only want to show user-facing images on the site.

File: docs/index.md

hide:

  • navigation

Custom Operating System images based on Fedora

This is a collection of container images using Fedora's support for OCI/Docker containers as a transport and delivery mechanism for operating system content. That's nerd-speak for the ultimate Linux client: the reliability of a Chromebook, but with the flexibility and power of a traditional Linux desktop. At long last, we've ascended!

This project provides:

  • :material-train-car-container:{ .lg .middle } Images

  • :material-heart:{ .lg .middle } Community

    Help new contributors to start their cloud native and open source journeys no matter their skill level.

Our main images offer GNOME, KDE, XFCE, LXQt, Budgie, and MATE, with more being added regularly. Our NVIDIA images offer a unique blend of reliability and ease of use that you won't find anywhere else.

These are offered in a variety of images to fit the needs of your hardware:

End-User Focused Images

  • Bazzite - The ultimate gaming setup for your PC, Steam Deck, ASUS ROG Ally and Legion Go. Fedora's upstream pipeline automated directly to your device, nice.

  • Bluefin - A simple to use desktop with the mission of serving a mass audience.

    • Bluefin DX Edition - Designed to be the ultimate Linux workstation for open source developers.

Why would I use these?

These images reflect a more cloud-native approach to running Linux on your desktop. We feel that a dedicated group of enthusiasts can automate a large amount of toil that plagues existing Linux desktops today. This is achieved by reusing cloud technologies as a delivery mechanism to deliver a more reliable experience, and to quote the goals of bootc:

"A top-level goal is that every tool and technique a Linux system administrator knows around how to build, inspect, mirror and manage application containers also applies to bootable host systems."

We like the sound of that, and we're hoping to be your "Desktop DevOps" team. Bringing the patterns from the server world to the desktop world means that there is a new layer on top of the distribution.

Users can now atomically share maintenance of things that people currently do by hand as post-installation. Universal Blue automates these changes. Contributors use a GitOps approach to maintaining these images, all out in the open for anyone to inspect, resulting in a system that now leverages the expertise of system administrators right to your desktop.

Advantages over traditional Linux desktops

  • Reliable, atomic updates with built in rollback
  • Known-good state and fewer failures
    • Significantly reduced configuration drift
    • No compiling or building Nvidia drivers on the local client, they come pre-made on the image
    • Kernel mods right on the image
  • Clean separation of the base system from applications and your data
    • Integration of Flatpak applications via Flathub
    • Toolbox and Distrobox support, run applications from any distribution in a containerized environment
  • Unbridled customization
    • Craft your perfect image from scratch or derive from others
  • Community Maintained
    • The project is maintained by a community of cloud-native contributors with an explicit mission
  • Reuses standards-based tooling from cloud
  • Built-in container tools for developers
    • Consume packages and software from any repo without risking breakage on the client
    • Easy consumption of other OCI images if it's on the CNCF Landscape
      • It's a first class citizen thanks to Podman

!!! example "What we mean by reliability:"

text
An important concept with this model is that the system is designed to reliably deliver your software. Software bugs and issues still occur with individual software. We mean reliability when it comes to installation and upgrades of the entire system, if you were destined to get a kernel bug that day, it still happens. This might sound counterintuitive at first, but be level of efficiency improves so dramatically over the long term that it allows developers to catch issues earlier in the testing process. This is awesome stuff, ask your local cloud nerd.

Other Features

  • Rebase back to pure Fedora without reinstallation
    - This is why we don't call it a distribution, it's an atomic layer of customization on an existing distribution that can be removed
  • Fast updates: minimum of once-a-day updates so you're never behind Fedora
  • Hosted on ghcr.io:
    • Ninety (90) days of image archives allowing for flexible rollback options
    • Globally distributed via CDN for fast image downloads, thanks Microsoft!
  • Images signed with standard sigstore tools
  • More features are explained in this video:

Join Us

If you want to learn, come hang out on our forums. We are here to teach and learn from each other! We're always looking for people to help, all skill levels and areas of expertise are welcome. Check out the roadmap to get a feel for the project, then:

If you're building your own custom images feel free to add them to our awesome list!

File: docs/introduction.md

Introduction to image-based Linux distributions from Fedora and Universal Blue

"Image-based," in the context of Linux distributions, means that the operating system is packaged as an image and everything added by the user is considered a separate layer. In image-based distributions, the root filesystem is mounted as read-only while the OS is booted. This means that all the changes to the base system are only applied after a reboot. Fedora uses ostree (like git for the filesystem) for its atomic filesystem updates and rpm-ostree (specialized equivalent of Fedora's dnf) for the image and package management system.

What does Universal Blue do?

Universal Blue uses the "OSTree Native Containers" feature of Fedora which enables using OCI container images to distribute the operating system.

The Universal Blue project builds light-touch images of the image-based Fedora variants with quality-of-life additions that don't diverge too much from the base of Fedora. Read more about our goals on the Scope page..
Additionally, the project works on more opinionated images such as Bluefin and Bazzite, and develops related utilities such as yafti for first-boot setup and fleek for managing your home directory with Nix.

We also provide tools for users to build their own image using our templates and processes, which can be used to ship some light configuration to all of your machines, or finally make the Linux distribution you've long wished for, but never had the tools to create. Read more about creating your own image here..

Cloud-native

All of Universal Blue rests on the idea of cloud-native. We leverage standard cloud tools like the OCI standard and the GitHub Container Registry to build our images. This is a much lighter and faster way of building and deploying Linux environments to users that allows professionals in the industry to leverage their pre-existing knowledge to create a better desktop Linux experience.

Mindset

Best practices when using an image-based Linux distribution differ from more traditional Linux environments. For example, installing software is typically done in a container or a different method rather than using the system package manager. Read more about other ways of installing software here.

Most documentation around "how do I do XYZ in Fedora/Linux" will not apply. Instead, you can do things such as running a web-server with podman and containers. And for setting up development or installing software not available as Flatpaks you should use some encapsulated user-space environment such as a toolbox or devbox.

You should familiarize yourself with the documentation of Universal Blue and related projects:

You can always ask for help from our Community (see sidebar).

Read-only and writable directories

Image-based Fedora variants follow the Filesystem Hierarchy Standard while mounting some directories as read-only and symlinking some from their actual location to their FHS-compatible location.

/usr/ is read-only when booted while /var/ and /etc/ are writable. Everything in /var/ is locally managed and cannot be directly changed by images. Certain directories in the root directory are symlinked to either /usr/ or /var/, for example, /home/ is symlinked to /var/home/. /usr/local/ is writable and files can be added, and system configuration modified there.

Explore Related Technologies & Topics

View All 9,111+ Repositories →

Discover similar high-velocity repositories, agent skills, and OpenAPI specifications across the ecosystem.

#desktop Browse desktop catalog → #fedora-kinoite Browse fedora-kinoite catalog → #fedora-linux Browse fedora-linux catalog → #fedora-silverblue Browse fedora-silverblue catalog → #gaming Browse gaming catalog → #htpc Browse htpc catalog → ⚡ MCP Servers Model Context Protocol → 🧠 Agent Skills Prompt & rule files → 🔌 OpenAPI Specs REST & Swagger schemas →