{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"Getting Started","text":"<ul> <li> <p> Installing Bazzite</p> <p>Bazzite supports PC hardware from most modern desktop and laptops to specialized models like Framework. </p> <p>Bazzite also supports controller-friendly hardware like home theater PC setups and a multitude of handhelds:</p> <ul> <li>Asus Handhelds</li> <li>Lenovo Handhelds</li> <li>GPD Handhelds</li> <li>OneXPlayer Handhelds</li> <li>Ayn Handhelds</li> <li>Ayaneo Handhelds</li> <li>Steam Deck</li> <li>Other PC Handhelds</li> </ul> </li> </ul> <ul> <li> <p> Playing Video Games</p> <p>Bazzite comes bundled with  Steam and Lutris to run all of your PC games<sup>1</sup> on multiple hardware configurations!</p> <p>It is also compatible with other tools like:</p> <ul> <li>Heroic Games Launcher for seamless Epic Games, GOG, and Amazon Games integration.</li> <li>Games and emulators from the built-in app store that range from osu! to Minecraft.</li> <li>...And more!</li> </ul> <p>*<sup>1</sup> PC games that are known to work on the Linux desktop, visit ProtonDB and Are We Anti-Cheat Yet? for more information.</p> </li> </ul> <ul> <li> <p> Installing Software</p> <p>Order reflects the recommendation degree.</p> <ol> <li>Bazzite Portal to use Bazzite tailored installers.</li> <li>Bazaar App Store (Flatpak) for most apps.</li> <li>Homebrew for command-line apps and tools.</li> <li>Containers for access to most Linux package managers (<code>apt</code>, <code>dnf</code>, <code>pacman</code>, etc.), as development toolboxes, and for hosting services.</li> <li>Appimage for portable apps found on the web.</li> </ol> <p>There is also package layering with <code>rpm-ostree</code>, but it is advised to avoid using it if possible since layered packages can break future upgrades until packages are removed.</p> </li> </ul> <ul> <li> <p> Updates &amp; Rollbacks</p> <p>Hassle-free updates with protections against regressions. Rollback to the previous deployment or rebase to an earlier Bazzite build within the last 90 days without losing your personal files.</p> <ul> <li>Updating Guide</li> <li>Rollback System Updates</li> <li>Rebasing to Other Images</li> <li><code>bazzite-rollback-helper</code></li> </ul> </li> </ul> <ul> <li> <p> Android Applications</p> <p>Run Android applications in a container using Waydroid!</p> <ul> <li>Launch anything from productivity software to games.</li> <li>ARM translation support for most applications.</li> <li>Use your favorite streaming service without the limitations of DRM.</li> <li>Install software through Google Play Store and F-Droid.</li> </ul> </li> </ul> <ul> <li> <p> Contributing</p> <p>One of the strengths of Bazzite (inherited from Universal Blue) is how easy it is to contribute.</p> <ul> <li>Something seems broken? You might want to report a bug.</li> <li>Add new changes by testing them in a custom image.</li> <li>Editing current documentation and adding translations are also appreciated.</li> </ul> </li> </ul>"},{"location":"community/","title":"Community","text":""},{"location":"community/#forums","title":"Forums","text":""},{"location":"community/#discord-no-discord-account","title":"Discord <sup>(No Discord account?)</sup>","text":""},{"location":"community/#bluesky","title":"Bluesky","text":""},{"location":"community/#xtwitter-no-xtwitter-account","title":"X/Twitter <sup>(No X/Twitter account?)</sup>","text":""},{"location":"community/#reddit","title":"Reddit","text":""},{"location":"community/#lemmy","title":"Lemmy","text":""},{"location":"donations/","title":"Credits and Donating","text":"<p>Enjoy using Bazzite and want to help sustain its development? Consider sponsoring the project and its individual maintainers and contributors.</p> Sponsor Bazzite ($ USA) Sponsor Bazzite (\u20ac Europe)"},{"location":"donations/#bazzite-maintainers","title":"Bazzite Maintainers","text":"Kyle Gospodnetich Sponsor Founder, Image &amp; CI/CD Lead HikariKnight Sponsor Virtualization, Scripting, User Support Noel Miller Sponsor Community Manager, Installer Enhancements, Custom Image Tooling"},{"location":"donations/#bazzite-core-contributors","title":"Bazzite Core Contributors","text":"Zeglius Sponsor Scripting, Documentation Maintenance, Live ISOs Maintainer CheckYourFax Community Support, Issue Wrangling Valerie Social Media Manager, Technical Support Am\u00e9lia Logo and Mascot Creator Kurt Himebauch ujust Extraordinaire. Decky wrangler. Framegen. Zacharias Xenakis Bazzite Portal, UX enhancements, bug fixes &amp; translations stellaberrant Translations and bug fixes wolfyreload Visual Guides on Youtube, QA Testing CharlieBros Language Translations in Spanish Crono Sponsor Does not think of himself as a contributor, but helps with significant testing"},{"location":"donations/#universal-blue","title":"Universal Blue","text":"<p>Special thanks to Universal Blue's Emeritus who has contributed in the early days of the project.</p> Jorge Castro Sponsor Universal Blue founder, Bluefin Lead Maintainer, Co-creator of Bazzite DX edition Niklas Haiden Aurora Lead Maintainer, Co-creator of Bazzite DX edition Benjamin Sherman uCore Lead Maintainer, Kernel modules maintainer, UBlue Main image maintainer m2 Kernel modules maintainer, UBlue Main image maintainer. Bug Fixes &amp; Enhancements. Tulip Blossom Sponsor Bluefin Maintainer, Leads Wolfi Bluefin expansion. Numerous fixes affecting Bazzite. Gareth Widlansky Image Maintenance"},{"location":"donations/#other-contributors","title":"Other Contributors","text":"RJ Trujillo Early Maintainer of Bazzite. CI/CD Pipelines, Initial Alternate Desktop Environment Support, and proper Steam Deck support. Emeritus. Pat Connors Documentation Aarron Lee Decky plugin creator for alternate handhelds. Provided a lot of early testing, especially with GPD and Legion Go devices. Emeritus. Jan Early Kernel maintainer of Bazzite through the kernel-fsync project. Emeritus. Sean Srock Animator. Early Ally tester. Creator of Bazzite Boot/Sleep animations. Bouhaa Early ChimeraOS maintainer that provided invaluable testing with gamemode session. Emeritus. RoyalOughtness Sponsor secureblue maintainer. Provides bug fixes related to security. Jason Nagin Creator of the non-Live Installer and its build action. Marco Rodolfi Bug Fixes &amp; Enhancements FiftyDinar Bug Fixes &amp; Enhancements Matthew Schwartz Steam Gaming Mode Testing &amp; Consulting Atapi Driver Backports XYNY Infographics &amp; Alternate Custom Tooling termdisc Technical Support Justin Garrison Developer Relations Ian Off QA Testing Alex Banna Prototyping Tony Pilot Brian Ketelsen Tooling Expert <p>View the full list of Bazzite contributors in the GitHub repository</p>"},{"location":"donations/#fedora-project","title":"Fedora Project","text":"<p>Bazzite would not exist without Fedora Linux since it is built directly on top of it.  The Fedora Project does not take monetary donations, but values hardware donations and contributions to the project:</p> <ul> <li>Donating Hardware</li> <li>Contributing</li> </ul>"},{"location":"donations/#software-included-in-bazzite","title":"Software Included in Bazzite","text":"<p>We also encourage you to donate to the projects that are used in Bazzite which helps us keep open source sustainable!</p> <p><sub>(If we missed software that is part of Bazzite and can be donated to, then please let us know or PR a fix!)</sub></p> <ul> <li>Atuin</li> <li>Bazaar</li> <li>Blur My Shell</li> <li>Clapper</li> <li>Davincibox</li> <li>Deja Dup</li> <li>Extensions Manager</li> <li>eza</li> <li>fastfetch</li> <li>fd (David Peter and Tavian Barnes)</li> <li>fzf</li> <li>freedesktop.org</li> <li>Gear Lever</li> <li>GNOME</li> <li>GNOME themes for Firefox and Thunderbird</li> <li>Hanabi</li> <li>Handheld Daemon</li> <li>Homebrew</li> <li>Just Perfection</li> <li>KDE</li> <li>Logo Menu</li> <li>Mozilla</li> <li>Pika Backup</li> <li>Terra</li> <li>Thunderbird</li> <li>Warehouse</li> <li>Waydroid</li> <li>xone</li> <li>yq</li> </ul>"},{"location":"donations/#special-thanks","title":"Special Thanks","text":"<p>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:</p> <ul> <li>amelia.svg - For creating our logo and overall branding.</li> <li>SuperRiderTH - For creating our Steam game mode startup video.</li> <li>evlaV - For making Valve's code available and for being this person.</li> <li>ChimeraOS - For gamescope-session and for valuable support along the way.</li> <li>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.</li> <li>sentry - For assistance with needed kernel patches and for creating the kernel-fsync repo we now use.</li> <li>nicknamenamenick - For being the MVP nearly single-handedly upkeeping our documentation and support literature, and countless cases of helping users.</li> <li>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.</li> <li>cyrv6737 - For the initial inspiration and the base that became bazzite-arch.</li> </ul>"},{"location":"sb/","title":"Sb","text":""},{"location":"Advanced/","title":"Advanced Guides","text":"<ul> <li>Auto-Mounting Secondary Drives</li> <li>Managing Gamescope Using ScopeBuddy</li> <li>Custom Resolutions</li> <li>Bazzite Command-Line Tools</li> <li>Using Looking-Glass</li> <li>Best Shell Practices</li> <li>Booting to Rescue Mode</li> <li>Reset Forgotten User Password</li> <li>Using Swap for Additional Memory or Hibernation</li> <li>Show Detailed Init Logs During Boot</li> <li>How to Modify Initramfs and Dracut</li> <li>Creating A Custom Bazzite Image</li> <li>Changes to Sunshine on Bazzite</li> </ul>"},{"location":"Advanced/Auto-Mounting_Secondary_Drives/","title":"Auto-Mounting Secondary Drives","text":"<p>MicroSD cards automatically mount without any manual intervention required.</p>"},{"location":"Advanced/Auto-Mounting_Secondary_Drives/#video-guide","title":"Video Guide","text":""},{"location":"Advanced/Auto-Mounting_Secondary_Drives/#setup-an-auto-mounting-partition","title":"Setup an auto-mounting partition","text":"<ol> <li> <p>Open Gnome Disks, should have an icon like this. </p> </li> <li> <p>Wipe the partition you want to use, then use the leftover to create a new one.</p> <p></p> </li> <li> <p>Give the drive a name and a filesystem.</p> </li> </ol> <p>Bazzite only supports BTRFS/Ext4 filesystems for reporting issues.</p> <p> </p> <p>Now reboot, your partition should be mounted automatically. Should appear under <code>/run/media/system/PARTITION_NAME</code>.</p> <p></p>"},{"location":"Advanced/Auto-Mounting_Secondary_Drives/#manual-mounting","title":"Manual mounting","text":"<p>Append <code>,user,exec</code> at the end if it doesn't work properly.</p> <p></p>"},{"location":"Advanced/Auto-Mounting_Secondary_Drives/#troubleshooting","title":"Troubleshooting","text":""},{"location":"Advanced/Auto-Mounting_Secondary_Drives/#emergency-mode-after-mounting","title":"Emergency Mode after mounting?","text":"<p>This video tutorial shows how to recover from your mounting mistakes.</p> <p></p>"},{"location":"Advanced/Auto-Mounting_Secondary_Drives/#drives-will-not-auto-mount-despite-being-btrfsext4-requests-authentication-every-boot-to-mount","title":"Drives will not auto-mount despite being BTRFS/ext4 (Requests authentication every boot to mount)","text":"<ol> <li> <p>Mount the target disk(s).</p> </li> <li> <p>Open Gnome Disks and navigate to the target disk.</p> </li> <li> <p>Click on Additional Partition Options &gt; Edit Mount Options.</p> </li> <li> <p>Ensure \"User Session Defaults\" is FALSE and \"Mount at system startup\" is TRUE, then click \"Ok\".</p> </li> <li> <p>Repeat for any additional disks. You can confirm this worked by checking your Fstab file and seeing that the appropriate UUIDs have been added. <code>sudo cat /etc/fstab</code>.</p> </li> </ol>"},{"location":"Advanced/Best_Shell_Practices/","title":"Best Shell Practices","text":""},{"location":"Advanced/Best_Shell_Practices/#changing-the-default-terminal-shell","title":"Changing the default terminal shell","text":"<p>Note</p> <p>The procedure for changing the default terminal on Bazzite is the same as that for Project Bluefin since both are based on Universal Blue. These instructions are adapted from the Project Bluefin docs.</p> <p>Bazzite ships Ptyxis as the default terminal. It shows up as <code>Terminal</code> in the menu. It is strongly recommended that you change your shell via the terminal emulator instead of system-wide. Click on the Terminal settings and edit your profile:</p> <p></p> <p>Then select \"Use Custom Command\" and add the shell you want to use. <code>/usr/bin/fish</code> is included on the image and other shells like ZSH may be installed with Homebrew:</p> <p></p>"},{"location":"Advanced/Reset_Forgotten_User_Password/","title":"Reset Forgotten User Password","text":"<p>Important</p> <p>This method is only if you forgot your current user password! Changing your current password should be done through the desktop environment.</p> <p>Warning</p> <p>Follow this guide at your own discretion because you can break your system attempting any of this.</p> <p></p> <ol> <li>Reboot your device.</li> <li>Press Esc on the keyboard to reach the GRUB boot menu.    a. If you press Esc too many times, you may end up at a <code>grub&gt;</code> prompt.    b. Return to the boot menu by typing <code>exit</code> and pressing Enter</li> <li>Edit the last deployment by presssing E on your keyboard.</li> </ol> <p></p> <p>Edit the GRUB prompt and append <code>init=/bin/bash</code> to the line beginning with <code>linux</code>.</p> <p></p> <p>Continue boot process with Ctrl+X</p> <p>Once you are in the GRUB command line:</p> <ol> <li> <p>Temporarily mount SELinux</p> <p><code>mount -t selinuxfs selinuxfs /sys/fs/selinux</code></p> </li> <li> <p>Load SELinux policy</p> <p><code>/sbin/load_policy</code></p> </li> <li> <p>Enter your new password (i.e. <code>passwd bazzite</code>)</p> <p><code>passwd [INSERT USERNAME HERE]</code></p> </li> <li> <p>Sync</p> <p><code>sync</code></p> </li> <li> <p>Reboot</p> <p><code>/sbin/reboot -ff</code></p> </li> </ol> <p></p> <p>Your user password should now be reset.</p> <p>Thanks to Colin Walters for the solution.</p>"},{"location":"Advanced/Reset_Forgotten_User_Password/#not-working","title":"Not Working?","text":"<p>Many users forget steps regarding SELinux because of old habits. If you've created everything but the SELinux steps above, then the file <code>/etc/shadow</code> will be unreadable or unreachable by any process.</p> <p>The good way to check if <code>/etc/shadow</code> is in bad SELinux configuration is to execute following command:</p> <p><code>ls -Z /etc/shadow</code></p> <p></p> <p>You should also notice unlabeled_t on your side. You now have to fix the label on <code>/etc/shadow</code> with command below:</p> <p><code>restorecon -v /etc/shadow</code></p> <p>And then check result again with <code>ls -Z /etc/shadow</code>, which should lead to:</p> <p><code>system_u:object_r:shadow_t:s0   /etc/shadow</code></p> <p>Now the system is ready and you can reboot with <code>/sbin/reboot -ff</code>.</p>"},{"location":"Advanced/bazzite-cli/","title":"<code>bazzite-cli</code>","text":""},{"location":"Advanced/bazzite-cli/#what-is-bazzite-cli","title":"What is <code>bazzite-cli</code>?","text":""},{"location":"Advanced/bazzite-cli/#list-of-cli-tools","title":"List of CLI Tools","text":"<p>Bazzite's opt-in command line experience. <code>bazzite-cli</code> comes with command line tools such as:</p> <ul> <li>atuin - A tool for syncing shell history across machines.</li> <li>bash-preexec - Pre-execution and pre-command hooks for Bash (required by atuin).</li> <li>bat - A <code>cat</code> clone with syntax highlighting and Git integration.</li> <li>chezmoi - A tool to manage dotfiles across multiple machines.</li> <li>direnv - An environment switcher for the shell.</li> <li>dysk - A Linux utility to get information on filesystems.</li> <li>eza - A modern replacement for the <code>ls</code> command.</li> <li>fd - A simple, fast, and user-friendly alternative to <code>find</code>.</li> <li>gh - The official GitHub command-line tool.</li> <li>glab - The official GitLab command-line tool.</li> <li>ripgrep - A fast recursive file searcher that respects <code>.gitignore</code>.</li> <li>shellcheck - A static analysis tool for shell scripts.</li> <li>starship - A minimal, blazing-fast, and infinitely customizable prompt for any shell.</li> <li>stress-ng - A stress testing tool for Linux.</li> <li>tealdeer - A fast client for simplified <code>tldr</code> man pages.</li> <li>television - A blazingly fast general purpose fuzzy finder TUI.</li> <li>trash-cli - A command line interface to the freedesktop.org trashcan.</li> <li>ugrep - A faster, user-friendly <code>grep</code> replacement.</li> <li>yq - A command-line processor for YAML, JSON, and XML data.</li> <li>zoxide - A smarter <code>cd</code> command that learns your habits.</li> </ul> <p>The community may add new tools over time, re-running <code>ujust bazzite-cli</code> will install them.</p>"},{"location":"Advanced/bazzite-cli/#using-bazzite-cli-with-alternate-shells","title":"Using <code>bazzite-cli</code> With Alternate Shells","text":"<p>You can enable <code>bazzite-cli</code> for fish or zsh by pre-pending an override to the $SHELL variable to the command with:</p> <pre><code>SHELL=fish ujust bazzite-cli\nSHELL=zsh ujust bazzite-cli\n# Or do it all at once from bash with\nujust bazzite-cli &amp;&amp; SHELL=fish ujust bazzite-cli &amp;&amp; SHELL=zsh ujust bazzite-cli\n</code></pre>"},{"location":"Advanced/creating_custom_image/","title":"Creating A Custom Bazzite Image","text":""},{"location":"Advanced/creating_custom_image/#use-cases","title":"Use Cases","text":"<ul> <li>You want to swap out pre-installed system-level applications and other default choices, but want to stick close to Bazzite to get improvements automatically.     - For example: Bazzite has Waydroid baked into the image, but not setup or running by default.  If you desire to have this package uninstalled, then you could replace it or remove it.     - You need to layer something like VPN software that has to be on an image but you don't want to maintain your own standalone image. (Deriving off of others is always easier)     - You want a personal-use image with config and software changes, but also want to benefit from work being completed upstream.     - Different desktop environments or window managers as opposed to what Bazzite offers.</li> <li>You want to help the development of Bazzite by being able to test your contributions prior to submiting to the community.     - Hardware enablement, experimental features, confirming fixes ahead of merge.</li> </ul>"},{"location":"Advanced/creating_custom_image/#recommended-methods","title":"Recommended Methods","text":""},{"location":"Advanced/creating_custom_image/#option-a-using-the-image-template","title":"Option A - Using the Image template","text":"<p>Use the official template image to build off of to make your own custom Bazzite preferred over forking the project.</p>"},{"location":"Advanced/creating_custom_image/#video-guide","title":"Video Guide","text":""},{"location":"Advanced/creating_custom_image/#option-b-forking-bazzite","title":"Option B - Forking Bazzite","text":"<p>Sometimes you don't want to make a whole new image from scratch, you just want to change some things without too much extra work by forking Bazzite.  It is highly recommended to use the Pull application for Github to keep your fork in sync.</p>"},{"location":"Advanced/creating_custom_image/#option-c-using-bluebuild","title":"Option C - Using BlueBuild","text":"<p>BlueBuild is a project that orginally started as a starting point for Universal Blue custom image building and eventually became its own separate project.  All support for Blue-Build images should be directed to the appropriate communication channels outside of Universal Blue.</p>"},{"location":"Advanced/custom_resolution/","title":"Custom Resolutions","text":""},{"location":"Advanced/custom_resolution/#kscreen-doctor-kde-imagesdesktop-mode-only","title":"Kscreen-Doctor (KDE Images/Desktop Mode only)","text":"<p>Starting with Plasma 6.6, <code>kscreen-doctor</code> allows addition of a custom modeline. If you are on the KDE image, try to use that first!</p>"},{"location":"Advanced/custom_resolution/#guide-to-add-a-custom-resolution-using-kscreen-doctor","title":"Guide to add a custom resolution using <code>kscreen-doctor</code>","text":"<ol> <li>Run <code>kscreen-doctor -o</code> in the terminal.</li> <li>Find the ID of the monitor you want to add a mode for. You should see something similar to this: <pre><code>Output: 1 eDP-1 a17bb763-cbd3-4b3d-b7d3-7344112e71b7\n    enabled\n    connected\n    priority 1\n    Panel\n    replication source:0\n    Modes:  1:2880x1800@60.00!  2:2880x1800@120.00*  3:1600x1200@59.87...... # output omitted for brevity\n</code></pre>     For example, if you want to add a custom mode to eDP-1, your ID will be 1. Note this down.</li> <li>You can now construct the command to add your custom mode, following this format: <pre><code>kscreen-doctor output.&lt;ID&gt;.addCustomMode.&lt;Width&gt;.&lt;Height&gt;.&lt;Refresh&gt;.&lt;Scaling&gt;\n</code></pre>     Replace each of the options with what you want to set. Note that refresh rate is in mHz (millihertz), so a 75Hz refresh rate will correspond to <code>75000</code> in <code>&lt;refresh&gt;</code>. <code>&lt;Scaling&gt;</code> can be <code>full</code> or <code>reduced</code>. Use <code>full</code> to stretch the resolution to fill the screen, or <code>reduced</code> to add black bars to preserve the aspect ratio.<p>For example, the command for adding a custom resolution of 1920x1080@75Hz for display ID 1 that will be stretched to fill the screen would be: <pre><code>kscreen-doctor output.1.addCustomMode.1920.1080.75000.full\n</code></pre></p> </li> </ol>"},{"location":"Advanced/custom_resolution/#custom-resolution-helper","title":"Custom-Resolution-Helper","text":"<p>Remove any custom resolutions if you encounter an unexpected display issue with <code>crh rm all</code>. Any modifications to your device should be done appropriately at your own risk.</p> <p>Custom resolutions created with this method require a reboot to take effect.</p> <p>A command-line utility that assists with creating and managing custom resolutions for your Bazzite installation.</p>"},{"location":"Advanced/custom_resolution/#using-custom-resolution-helper","title":"Using <code>custom-resolution-helper</code>","text":"<p>Open a host terminal and enter:</p> <pre><code>custom-resolution-helper\n</code></pre> <p>There is also an alias which is less typing for those on handhelds or HTPC setups without a keyboard:</p> <pre><code>crh\n</code></pre>"},{"location":"Advanced/custom_resolution/#guide-for-creating-a-custom-resolution-using-custom-resolution-helper","title":"Guide for creating a custom resolution using <code>custom-resolution-helper</code>","text":"<ul> <li>ModeDB Method: easier to set up, will likely not work with HDMI.</li> <li>EDID Method: more hassle to set up, only use this if ModeDB does not work.</li> </ul> <p>Starting with Plasma 6.6, <code>kscreen-doctor</code> allows addition of a custom modeline. If you are on the KDE image and only need custom resolution in desktop mode, try to use that first!</p> Modedb methodEDID method <ol> <li>Run <code>custom-resolution-helper</code> in a terminal.</li> <li>Verify that you do not have a duplicate resolution.</li> <li>Choose <code>Add</code>, using arrow keys to navigate and enter to submit.</li> <li>Select the Display you want to create a custom resolution for. This display should be <code>connected</code>.</li> <li>Follow the Instructions on-screen in Interactive Mode.</li> <li>Once you finished selecting the options, you will get a prompt to change the boot configuration. Simply authorize it with your password.</li> <li>Once the command finishes, you can reboot and select the new resolution in your System Settings.</li> </ol> <ol> <li>Run <code>custom-resolution-helper</code> in a terminal.</li> <li>Choose <code>Dump-EDID</code> and select your display.</li> <li>The EDID will be placed in <code>/tmp/crh/edid.bin</code>.</li> <li>You can copy this to either Home, Downloads, or Desktop folder.</li> <li>We can use the familiar CRU to edit it, however, this will require a wine/proton launcher. You can use Lutris, Faugus launcher, or even Steam to open this.</li> <li>Once you open CRU, click the import option in the lower lefthand corner. Make sure files of type is set to \"all\", and \"Import complete EDID\" is selected. </li> <li>You can do your modifications to the edid, the same way as on Windows.</li> <li>Once you finish, save it as a file using the export option.</li> <li>Move the edited edid file to <code>/tmp/crh/edited/</code>, and select it in <code>crh add-edid</code>. You will get a prompt to change the boot configuration. Simply authorize it with your password.</li> <li>Once the command finishes, you can reboot and select the new resolution in your System Settings.</li> </ol>"},{"location":"Advanced/custom_resolution/#interactive-mode-option-explaination","title":"Interactive Mode Option Explaination:","text":"<ul> <li>VESA(TM) Coordinated Video Timings(CVT): Select this if your refresh rate is not currently selectable in System Settings (e.g. you are overclocking your display from 60Hz to 75Hz, but 75Hz is currently not an available refresh rate).</li> </ul> <ul> <li>Reduced Blanking: You will want this if your monitor has a high resolution or refresh rate. You can check Tom Verbeure's display timing calculator to learn more.</li> </ul> <ul> <li>Interlaced: This sets the resolution as interlaced, useful for something like a Plasma TV or CRT Display.</li> </ul> <ul> <li>Margins: This is useful when the margins of the picture are hidden beyond the borders of the screen, as if the picture is zoomed in. Most of the time you would want this to be adjusted in the Monitor/TV instead.</li> </ul>"},{"location":"Advanced/custom_resolution/#guide-for-creating-a-custom-resolution-for-sunshine-game-streaming","title":"Guide for creating a custom resolution for Sunshine Game Streaming","text":"<p>Let's say you are streaming from your host PC (running Bazzite) to your laptop:</p> <ul> <li>Your host desktop PC has a resolution of <code>1920x1080@144Hz</code>,</li> <li>but your laptop has a resolution of <code>2560x1600@120Hz</code>.</li> </ul> <p>...and text in the stream looks blurry because of resolution scaling.</p> <p>You can use <code>custom-resolution-helper</code> to add a virtual display to your host PC (running Bazzite) without a dummy plug!</p> <ul> <li>Simply follow the steps for creating a custom resolution, and select the option to make the display always enabled. After rebooting, you can press Super + P to switch multi-monitor modes on KDE. After that, make sure the correct display is selected in Sunshine.</li> </ul> <ul> <li>Alternatively, you can also add a <code>2560x1600MR@120</code> mode to your host PC's main display. This may cause your host PC's monitor to black out and show an <code>unsupported mode</code> dialog, and you will have to change the resolution during game streaming. You can try this method if you don't want to deal with multiple monitors.</li> </ul> <p>Do not disable the main display, as doing that may leave you with no available display out (which may also break streaming). If you do encounter a black screen that persists after rebooting, you can try going into a <code>tty</code> by pressing ctrl + alt + F2, and edit or remove <code>~/.config/kwinoutputconfig.json</code> from the command line. Note that this will remove your monitor configurations. An example command will be <code>mv ~/.config/kwinoutputconfig.json ~/.config/kwinoutputconfig.json.bak</code></p>"},{"location":"Advanced/custom_resolution/#advanced-usage","title":"Advanced Usage","text":"<p>This tool adds a kernel argument with <code>video=[RESOLUTION]</code>. The <code>[RESOLUTION]</code> string follows the format <code>&lt;name&gt;:&lt;xres&gt;x&lt;yres&gt;[M][R][-&lt;bpp&gt;][@&lt;refresh&gt;][i][m][eDd]</code>, as specified in the kernel documentation for modedb.</p> <p>If you feel confident enough and know what you are doing, you can use the</p> <pre><code>custom-resolution-helper add [RESOLUTION]\n</code></pre> <p>to add a resolution with functionality not included in this script, such as forcing a DVI-I port to use digital output.</p> <p>You can also manipulate kernel arguments directly via</p> <pre><code>rpm-ostree kargs --editor\n</code></pre> <p>However, please note that any modifications to your device should always be done appropriately at your own risk.</p>"},{"location":"Advanced/dracut-and-initramfs/","title":"How to Use Modprobe Options in Bazzite","text":""},{"location":"Advanced/dracut-and-initramfs/#if-you-just-plan-to-add-options-to-a-module-then-you-should-consider-using-a-karg","title":"If you just plan to add options to a module, then you should consider using a karg!","text":"<p>Touching the initramfs system and modprobe will slow down your updates so all your updates will take several minutes longer. In most cases what you want to do in modprobe can be done with simple kernel arguments.</p> <p>In this example lets change the below modprobe options into a karg (kernel argument): <pre><code>options hid_apple fnmode=2\n</code></pre> This would translate to the karg: <pre><code>hid_apple.fnmode=2\n</code></pre> To add this to grub we issue the command: <pre><code>rpm-ostree kargs --append-if-missing=\"hid_apple.fnmode=2\"\n</code></pre> This lets you change the module option without editing the initramfs system and is a lot faster whenever you update the system as the kernel arguments are not regenerated on each update.</p>"},{"location":"Advanced/dracut-and-initramfs/#upstream-documentation-on-modifying-kernel-arguments","title":"Upstream Documentation on Modifying Kernel Arguments","text":"<p>Read the upstream Fedora documentation on this topic for more information.</p>"},{"location":"Advanced/looking-glass/","title":"Installing Looking Glass","text":""},{"location":"Advanced/looking-glass/#read-first","title":"READ FIRST!","text":"<p>Looking-Glass is a very experimental project and is not ready for production use! This means there are no official packages for <code>looking-glass-client</code> yet.  For this reason we do not package or ship <code>looking-glass-client</code>, we only provide a working configuration and SELinux rules so that it can be used in Bazzite. We do however package the <code>kvmfr</code> kernel module and include it with the system image, as such file any issue with the <code>kvmfr</code> module in Bazzite to our Discord or Github issue tracker and make sure to ping @HikariKnight.</p> <p>We will only tell you to file an issue with Looking-Glass directly if the issue is not related to the packaging and configuration of the <code>kvmfr</code> module.</p>"},{"location":"Advanced/looking-glass/#enabling-the-kvmfr-module","title":"Enabling the KVMFR Module","text":"<p>You can enable the kvmfr module by running this command:</p> <pre><code>ujust setup-virtualization kvmfr\n</code></pre>"},{"location":"Advanced/looking-glass/#compiling-looking-glass-client","title":"Compiling Looking-Glass Client","text":"<p>Create a <code>fedora:latest</code> distrobox that we will use to compile the binary, use the following command to make the container, when asked about what image to use, select the default one as I have verified this guide works with that image for building. This distrobox has to be made manually without the <code>--nvidia</code> flag which our ujust automatically applies to enable hardware acceleration, however we explicitly do not want it in order to make <code>cmake-data</code> successfully install.</p> <p>Note</p> <p>If you are not using the latest Fedora version, please change <code>latest</code> to match your version number, this is to avoid dependency versioning issues.</p> <p><pre><code>distrobox create -i \"fedora:latest\" -n \"tmp-lookingglass\"\n</code></pre> If you want to use a separate home folder for this then make a folder to contain this containers home folder and run this command instead: <pre><code>distrobox create -i \"fedora:latest\" -n \"tmp-lookingglass\" -H \"/path/to/new/home\"\n</code></pre> Enter the container with <code>distrobox enter tmp-lookingglass</code></p> <p>Follow upstream documentation, you can find the fedora build dependencies here and you will also want to install the dependencies mentioned for PipeWire users. Since we will be building for Wayland and not X11 you will also need the package <code>libdecor-devel</code></p> <p>When you get to the part for running <code>cmake</code>, use the command: <pre><code>cmake -DENABLE_WAYLAND=1 -DENABLE_X11=0 -DENABLE_PULSEAUDIO=0 -DENABLE_PIPEWIRE=1 ..\n</code></pre> The above command will disable X11 support and Pulseaudio support, but enable Pipewire and Wayland support, this will avoid any issues as Bazzite does not ship the X11 dependencies for <code>looking-glass</code>.</p> <p>Copy the built <code>looking-glass-client</code> binary to <code>/run/host/home/$USER/.local/bin/</code> You can do that using the following commands if you followed the looking-glass documentation. <pre><code>mkdir /run/host/home/$USER/.local/bin\ncp ./looking-glass-client /run/host/home/$USER/.local/bin/\n</code></pre> Test and see if <code>looking-glass-client</code> binary works for you on the host with your VM running.</p> <p>Exit the container and run the below command to remove the container we used to build the Looking-Glass client. <pre><code>distrobox stop tmp-lookingglass ; distrobox rm tmp-lookingglass\n</code></pre></p>"},{"location":"Advanced/plymouth_init/","title":"Show Detailed Init Logs During Boot","text":""},{"location":"Advanced/plymouth_init/#purpose","title":"Purpose","text":"<p>See the init log show if services are functional when your device boots.</p> <p></p>"},{"location":"Advanced/plymouth_init/#1-change-initramfs-theme-to-enable-detailed-init-logs","title":"1 - Change Initramfs Theme to Enable Detailed Init Logs:","text":"<pre><code>sudo plymouth-set-default-theme details\n</code></pre> <p>Alternatively, create <code>/etc/plymouth/plymouthd.conf</code> manually</p>"},{"location":"Advanced/plymouth_init/#2-regenerate-initramfs-reboot-to-enable-theme-change","title":"2 - Regenerate Initramfs &amp; Reboot to Enable Theme Change","text":"<pre><code>sudo rpm-ostree initramfs --enable --reboot\n</code></pre>"},{"location":"Advanced/rescue-and-emergency-mode/","title":"Booting Into Rescue and Emergency Modes","text":""},{"location":"Advanced/rescue-and-emergency-mode/#preface","title":"Preface","text":"<p>Fedora already has a built-in mechanism (provided by <code>systemd</code>) for booting into rescue/emergency modes.</p> <p>However, Fedora (and thus Universal Blue systems), do not set a <code>root</code> password during install. Thus, when the emergency or rescue mode is reached, the user is shown the error:</p> <pre><code>Cannot open access to console, the root account is locked.\n</code></pre> We've improved the situation for all Universal Blue derivatives using inspiration from Fedora CoreOS. <p>Now, when booting to emergency or rescue mode with a locked root account, the user is instead presented a more standard prompt:</p> <pre><code>Press Enter for maintenance\n(or press Control-D to continue):\n</code></pre> <p>At this point, pressing Enter will drop the user into the appropriate root shell. SELinux will also be active in this mode (unless it has been disabled by other configuration), so this is a good mode to use if needing to reset your password, etc.</p> <p>See below for more details:</p>"},{"location":"Advanced/rescue-and-emergency-mode/#booting-to-emergency-mode","title":"Booting to Emergency Mode","text":"<p>Emergency mode provides the most minimal environment possible and allows you to repair your system even in situations when the system is unable to enter rescue mode. In emergency mode, the system mounts the <code>root</code> file system only for reading, does not attempt to mount any other local file systems, does not activate network interfaces, and only starts few essential services.</p> <ol> <li>Press Esc on the keyboard to reach the GRUB boot menu.    a. If you press Esc too many times, you may end up at a <code>grub&gt;</code> prompt.    b. Return to the boot menu by typing <code>exit</code> and pressing Enter</li> <li>Select the desired deployment (the top entry is generally correct) and edit by pressing E on the keyboard.</li> <li>Arrow down to the line starting with <code>linux</code> and press Ctrl+E to reach the end of the line.</li> <li>Add the word <code>emergency</code> to the end of the line.    a. Ensure there is a space between <code>emergency</code> and the pre-existing text.    b. Equivalent parameters <code>-b</code> and <code>systemd.unit=emergency.target</code> may be added instead of <code>emergency</code>.</li> <li>Press Ctrl+X to boot the system.</li> </ol>"},{"location":"Advanced/rescue-and-emergency-mode/#booting-to-rescue-mode","title":"Booting to Rescue Mode","text":"<p>Rescue mode provides a convenient single-user environment and allows you to repair your system in situations when it is unable to complete a normal booting process. In rescue mode, the system attempts to mount all local file systems and start some important system services, but it does not activate network interfaces or allow more users to be logged into the system at the same time. In Fedora, rescue mode is equivalent to single user mode.</p> <ol> <li>Press Esc on the keyboard to reach the GRUB boot menu.    a. If you press Esc too many times, you may end up at a <code>grub&gt;</code> prompt.    b. Return to the boot menu by typing <code>exit</code> and pressing Enter</li> <li>Select the desired deployment (the top entry is generally correct) and edit by pressing E on the keyboard.</li> <li>Arrow down to the line starting with <code>linux</code> and press Ctrl+E to reach the end of the line.</li> <li>Add the word <code>single</code> to the end of the line.    a. Ensure there is a space between <code>single</code> and the pre-existing text.    b. Equivalent parameters <code>1</code>, <code>s</code>, <code>S</code>, and <code>systemd.unit=rescue.target</code> may be added instead of <code>single</code>.</li> <li>Press Ctrl+X to boot the system.</li> </ol>"},{"location":"Advanced/rescue-and-emergency-mode/#root-shell-with-no-password-how-can-this-be-secure","title":"Root shell with no password! How can this be secure?","text":"<p>This improvement is implemented such that a user must have the ability to edit the kernel command line. If your bootloader (eg, GRUB) is configured with a password preventing users from modifying the kernel command line, bypassing the password for a locked root account will not be enabled. This is especially important since <code>emergency</code> mode can be reached when a filesystem check fails at boot time, not just when specified on the kernel command line.</p> <p>Given this safeguard, this improved rescue &amp; emergency method is just as secure as setting <code>init=/bin/bash</code>, etc. Plus, it is less likely a user will damage SELinux labels using this method.</p>"},{"location":"Advanced/rescue-and-emergency-mode/#reset-forgotten-user-password","title":"Reset Forgotten User Password","text":"<p>Forgot the user password to login?  Read the Fedora Documentation on this topic.  Please remember that the default password for all new Bazzite installations is \"bazzite\" if you did not set one during the installation setup.</p>"},{"location":"Advanced/scopebuddy/","title":"ScopeBuddy","text":""},{"location":"Advanced/scopebuddy/#what-is-it","title":"What is it?","text":"<ul> <li>A small script that works as a gamescope bridge to avoid having to copy paste long launch options for many games.</li> <li>Allows you to set Environment Variables (env vars) and gamescope launch options globally, per game or depending on what mode ScopeBuddy or Steam is running in.</li> <li>Gives you the ability to automate running bash scripts before the game runs (this is a side effect of how the config files work)</li> <li>You can bring your configurations with you between computers by just copying <code>~/.config/scopebuddy</code> to a new device</li> <li>It also is used as a workaround to fix the Steam Overlay when using nested gamescope in desktop mode.</li> <li>Fixes SteamInput when used in nested mode on Desktop.</li> </ul>"},{"location":"Advanced/scopebuddy/#how-to-use-it","title":"How to use it","text":"<p>As a <code>gamescope</code> replacement just to fix the Steam Overlay:</p> <p>If you just want to fix the Steam Overlay (and Steam Input in some games), all you have to do is replace <code>gamescope</code> in your launch options for the game with <code>scb</code> or <code>ScopeBuddy</code>. Essentially turning</p> <pre><code>XDG_DEFAULT_LAYOUT=no gamescope -w 1920 -h 1080 -W 2560 -H 1440 -- %command% --launcher-skip\n</code></pre> <p>Into</p> <pre><code>XDG_DEFAULT_LAYOUT=no scb -w 1920 -h 1080 -W 2560 -H 1440 -- %command% --launcher-skip\n</code></pre> <p>Now your Steam Overlay will work when using gamescope for a game in desktop mode! \ud83c\udf89</p>"},{"location":"Advanced/scopebuddy/#usage-in-lutris","title":"Usage in Lutris","text":"<ol> <li>Open Lutris and right click on the game you want to use ScopeBuddy with.</li> <li>Click <code>Configure</code></li> <li>Go to the <code>System Options</code> tab and scroll down to <code>Game execution</code></li> <li>Click <code>Add</code> under <code>Environment variables</code> and set the key to <code>SCB_APPID</code> and the value to <code>lutris/nameofgame</code>.</li> <li>In the <code>Command prefix</code> add <code>scb --</code></li> <li>Click Save</li> </ol> <p>The <code>SCB_APPID</code> Environment variable is optional, but will let you take advantage of game specific config files</p>"},{"location":"Advanced/scopebuddy/#configuration-files","title":"Configuration files","text":""},{"location":"Advanced/scopebuddy/#setting-global-defaults","title":"Setting global defaults","text":"<p>If you ran your game once with the above launch options, ScopeBuddy will have created a default example config for you <code>~/.config/scopebuddy/scb.conf</code></p> <p>It might be possible that the file doesnt exists, in such case, create an empty one.</p> <p>Inside the file you can add env vars and setup a default set of gamescope arguments.</p> <pre><code>export XDG_DEFAULT_LAYOUT=no\nSCB_GAMESCOPE_ARGS=\"-f -w 2560 -h 1440 -W 2560 -H 1440 -r 180\"\n</code></pre> <p>The above <code>scb.conf</code> will make ScopeBuddy always set the keyboard layout in gamescope to norwegian and run gamescope with the arguments <code>-f -w 1920 -h 1080 -W 2560 -H 1440 -r 180</code></p> <p>This means we can now shorten our Launch Options for games we want to run in gamescope to just</p> <pre><code>scb -- %command% --launcher-skip\n</code></pre> <p>Note</p> <p><code>--launcher-skip</code> is just an example launch option</p>"},{"location":"Advanced/scopebuddy/#auto-resolutionhdrvrr","title":"Auto Resolution/HDR/VRR","text":"<p>For users that routinely change resolutions or use game streaming via Sunshine/Moonlight or Steam Remote Play, your display properties may change frequently.</p> <p>On KDE desktops (early Gnome support added with caveats), ScopeBuddy accepts configuration to automatically inject the width and height, HDR state, or VRR state of your primary display.</p> <p>Add the following variables to the following to the config file at <code>~/config/scopebuddy/scb.conf</code>:</p> <p><pre><code>SCB_AUTO_RES=1 # Overrides output height and width with current display\nSCB_AUTO_HDR=1 # Adds --enable-hdr if the current display has HDR enabled\nSCB_AUTO_VRR=1 # Adds --adaptive-sync if the current display has VRR enabled\n</code></pre> If you have multiple displays (or a streaming \"dummy plug\"), these values will be detected from your primary display in KDE.</p> <p>Hard-coding a specific display in your <code>SCB_GAMESCOPE_ARGS</code> with <code>--prefer-output {your-device-here}</code> will make these automatic values detect from the preferred display.</p> <p>A full config example using SCB_AUTO_* vars might look like:</p> <pre><code>SCB_GAMESCOPE_ARGS=\"-f --mangoapp\" # passes args for fullscreen + mangohud to gamescope\nSCB_AUTO_RES=1\nSCB_AUTO_HDR=1\nSCB_AUTO_VRR=1\n</code></pre> <p>This will result in the following gamescope command output when your KDE display is set to 2560x1440 with HDR and VRR on:  <code>gamescope -f --mangoapp -W 2560 -H 1440 --hdr-enabled --adaptive-sync</code>.</p> <p>Later, if you switch your KDE display to 1920x1080 with HDR off and VRR on:  <code>gamescope -f --mangoapp -W 1920 -H 1080 --adaptive-sync</code>.</p> <p>All without changing a single line in your Steam launch options or ScopeBuddy config!</p>"},{"location":"Advanced/scopebuddy/#additional-config-files","title":"Additional Config Files","text":"<p>If you have a different set of defaults you use for a game, for example you want to upscale this game from 1080p to 1440p, then you can have a separate default config and tell ScopeBuddy to use that instead. For this example, make the file <code>1080p.conf</code> inside <code>~/.config/scopebuddy/</code> and add defaults specific to what you want to use for upscaling from 1080p.</p> <pre><code>export XDG_DEFAULT_LAYOUT=no\nSCB_GAMESCOPE_ARGS=\"-f -w 1920 -h 1080 -W 2560 -H 1440 -r 180\"\n</code></pre> <p>To use this new config you can tell ScopeBuddy to use it by setting the <code>SCB_CONF</code> env var in the games Launch Option in steam</p> <pre><code>SCB_CONF=1080p.conf scb -- %command% --launcher-skip\n</code></pre> <p>ScopeBuddy will now use <code>1080p.conf</code> instead of <code>scb.conf</code> to set default options and environment variables.</p> <p>Note</p> <p>If you supply any argument to ScopeBuddy then <code>SCB_GAMESCOPE_ARGS</code> will be ignored entirely! This means using the launch option <code>scb -f -- %command%</code> will load the env vars from <code>scb.conf</code> however it will not use <code>SCB_GAMESCOPE_ARGS</code> from any config files.</p>"},{"location":"Advanced/scopebuddy/#setting-specific-options-for-a-single-steam-game","title":"Setting specific options for a single Steam game","text":"<p>For this example we will use Path of Exile 2, this game supports HDR, so we want to append the <code>--hdr-enabled</code> argument to gamescope.</p> <p>First we will need to find Path of Exile 2's Steam AppID, you can find this by going to the games Properties in Steam and then heading to the Updates section. At the bottom you will see some information, you want the App ID value, in our Path of Exile 2 example this is <code>2694490</code>.</p> <p>Now make <code>2694490.conf</code> inside <code>~/.config/scopebuddy/AppID/</code> and add your Path of Exile 2 specific options. And for examples sake let's set <code>SteamDeck</code> to <code>0</code>, because let us say the game enforces settings that are only relevant on Steam Deck hardware, so we turn off announcing to the game that we are on the Steam Deck Client.</p> <pre><code>export SteamDeck=0\nSCB_GAMESCOPE_ARGS+=\" --hdr-enabled\"\n</code></pre> <p>Now when steam runs <code>scb -- %command%</code>, ScopeBuddy will load the config from <code>scb.conf</code> then load <code>AppID/2694490.conf</code> afterwards to apply extra options on top of the defaults (or replace previous options from the default config if the same variables are exported or changed again)</p> <p>Notice how <code>SCB_GAMESCOPE_ARGS</code> uses <code>+=</code> instead of <code>=</code>.</p> <ul> <li><code>+=</code> means append this at the end of the current variable.</li> <li><code>=</code> means to replace everything in the variable.</li> </ul> <p>This let's us re-use the <code>SCB_GAMESCOPE_ARGS</code> we set in our <code>scb.conf</code></p> <p>Note</p> <p>You can also set an AppID manually using <code>SCB_APPID=\"somecoolgame\"</code> to override the automatic AppID detection which only supports Steam currently. This can be used to manually add rudimentary support for \"AppID\"-like configs for games in other launchers like Lutris or Heroic; for example, <code>SCB_APPID=\"heroic/somecoolgame\"</code> would use the config file <code>AppID/heroic/somecoolgame.conf</code>.</p>"},{"location":"Advanced/scopebuddy/#frequently-asked-questions-faq","title":"Frequently asked questions (FAQ)","text":""},{"location":"Advanced/scopebuddy/#is-there-a-graphical-application-for-making-configurations","title":"Is there a graphical application for making configurations?","text":"<p>Yes! There is one on flathub: ScopeBuddy GUI</p>"},{"location":"Advanced/scopebuddy/#can-i-use-scopebuddys-functions-without-using-gamescope","title":"Can I use ScopeBuddys functions without using gamescope?","text":"<p>Yes, just use the env var <code>SCB_NOSCOPE=1</code> in the Launch Options like this</p> <pre><code>SCB_NOSCOPE=1 scb -- %command% --launcher-skip\n</code></pre> <p>This will tell ScopeBuddy to not launch gamescope and ignore <code>SCB_GAMESCOPE_ARGS</code> in all configs. The default config file will also be set to <code>noscope.conf</code> instead of <code>scb.conf</code> unless you also added the <code>SCB_CONF</code> env var to the launch options.</p> <p>Note</p> <p>You can also export <code>SCB_NOSCOPE=1</code> inside an appid config if you never want to use gamescope for a game but still use ScopeBuddy for it. However <code>noscope.conf</code> will be ignored when used like this, due to it being applied after <code>scb.conf</code> has been loaded.</p>"},{"location":"Advanced/scopebuddy/#does-scopebuddy-work-inside-steam-gaming-mode","title":"Does ScopeBuddy work inside Steam Gaming Mode?","text":"<p>Yes! When ScopeBuddy detects that steam is running in Steam Gaming Mode, it will force <code>SCB_NOSCOPE=1</code> and <code>SCB_CONF=gamemode.conf</code> so that you can set custom options that will only be used in Steam Gaming Mode while keeping game specific options!</p> <p>This means you can use ScopeBuddy to automatically handle using nested gamescope when in desktop mode and not utilizing gamescope when inside Steam Gaming Mode. No more manually adding and removing gamescope from launch options when you switch between Steam Gaming Mode and Desktop Mode! \ud83c\udf89</p>"},{"location":"Advanced/scopebuddy/#can-i-have-scopebuddy-handle-the-launch-options-for-my-games","title":"Can I have ScopeBuddy handle the launch options for my games?","text":"<p>Of course! You will just use an AppID config for this and you can then append launch options by adding this to the AppID config for the game.</p> <pre><code>command+=\" --launcher-skip --some-other-parameter\"\n</code></pre> <p>Note</p> <p>The <code>+=</code> is very important as you NEED to append launch options to the %command%, it is also vital that you start with a space after the first \" otherwise the game will fail to launch.</p>"},{"location":"Advanced/scopebuddy/#can-i-have-scopebuddy-not-apply-its-fixes-and-only-use-it-as-a-gamescope-manager","title":"Can I have ScopeBuddy not apply its fixes and only use it as a gamescope manager?","text":"<p>Using the following environment variables will change ScopeBuddy's default behavior</p> <ul> <li><code>SCB_APPENDMODE=1</code> setting this in <code>scb.conf</code> will let you supply arguments to ScopeBuddy and they will be appended after the gamescope arguments in any config files.</li> <li><code>SCB_STEAMARGIGNORE=0</code> setting this in <code>scb.conf</code> will make ScopeBuddy no longer strip the <code>-e</code> or <code>--steam</code> arguments if it is supplied to gamescope, this is due to this specific flag currently crashing gamescope.</li> <li><code>SCB_NESTEDFIX=0</code> setting this in <code>scb.conf</code> will disable the Steam Overlay and SteamInput fix that ScopeBuddy applies (before you ask, they are the same fix)</li> </ul> <p>Note</p> <p>See XKCD 1172 for context to why these environment variables exist</p>"},{"location":"Advanced/scopebuddy/#when-should-i-use-export-for-an-environment-variable","title":"When should I use export for an environment variable?","text":"<p>This depends if it is an internal variable for ScopeBuddy or a global variable for games. Rule of thumb is that you export every environment variable except in the situation of</p> <ul> <li>It starts with <code>SCB_</code> as these are all internal ScopeBuddy variables</li> <li>The variable is named <code>command</code> as this is the internal ScopeBuddy variable containing everything inside <code>%command%</code> from steam (or everything after the <code>--</code>)</li> </ul>"},{"location":"Advanced/scopebuddy/#wait-this-is-all-just-bash","title":"Wait... This is all just Bash!?","text":"<p>Every config file for ScopeBuddy is a full bash script that is sourced before running gamescope and the game. This means if you are an advanced user you can do some really creative stuff! You can also set <code>SCB_DEBUG=1</code> to have the final command written to <code>~/.config/scopebuddy/scopebuddy.log</code></p> <p>Note</p> <p>Steam will mess with the launch environment, some tools like <code>curl</code> will have incompatible libraries in the environment while <code>wget</code> will work fine. Test your scripts properly and have them write to a log for easy debugging using <code>2&gt;&amp;1 1&gt;/tmp/myscript.log</code> at the end of it in the config to write the output to a log file during testing.</p> <p>Some handy variables available to you are</p> <ul> <li><code>$SCB_NOSCOPE</code> will be set to 1 if ScopeBuddy was launched with <code>SCB_NOSCOPE=1</code></li> <li><code>$SCB_GAMEMODE</code> will be set to 1 if ScopeBuddy is ran from within steam Steam Gaming Mode (this also implies <code>SCB_NOSCOPE=1</code>)</li> <li><code>$SCB_CONFIGDIR</code> will be <code>$HOME/.config/scopebuddy</code> this means you can source other configs within your config (please do not make an infinite loop!)</li> <li><code>$command</code> will contain the expanded %command% variable from Steam and any launch options you added after it.</li> </ul> <p>Let your creativity go wild! But please be responsible!</p>"},{"location":"Advanced/scopebuddy/#script-example-for-an-arcdps-updater-for-guild-wars-2","title":"Script example for an ArcDPS updater for Guild Wars 2","text":"<p>This is meant as inspiration for any ideas you might have?</p> <p>Make a config file for Guild Wars 2 AppID/1284210.conf</p> <pre><code># Guild Wars 2\n# Do not use gamescope for this title\nSCB_NOSCOPE=1\n# Use ArenaNet login instead of Steam\ncommand+=\" -provider Portal\"\n\n# Get the game directory from the expanded %command% variable from steam\nGAMEDIR=$(echo $command | awk -F '\" \"' '{ print $12 }' | sed 's/\\/Gw2-64.exe//')\n# Run the arcdps updater script before game starts\n\"$SCB_CONFIGDIR/scripts/dl-arcdps\" \"$GAMEDIR\"\n</code></pre> <p>Then make the script file (remember to make it executable) scripts/dl-arcdps</p> <pre><code>#!/bin/bash\n# Get the directory passed to the script\nGW2_DIR=$1\n# Get the latest md5sum for arcdps\nNEWMD5SUM=$(wget -qO- https://www.deltaconnected.com/arcdps/x64/d3d11.dll.md5sum | awk '{print $1}')\n# Get installed arcdps md5sum\nMD5SUM=$(md5sum \"$GW2_DIR/d3d11.dll\" 2&gt;/dev/null | awk '{print $1}')\n# If they do not match, ask to update arcdps\nif [ \"$MD5SUM\" != \"$NEWMD5SUM\" ]; then\n    if zenity --question --text=\"Update ArcDPS?\\nNew MD5: $NEWMD5SUM\\nOld MD5: $MD5SUM\"; then\n        # Use wget to download arcdps as curl does not work in the steam environment\n        wget -O \"$GW2_DIR/d3d11.dll\" https://www.deltaconnected.com/arcdps/x64/d3d11.dll\n    fi\nfi\n</code></pre>"},{"location":"Advanced/scopebuddy/#video-overview","title":"Video Overview","text":""},{"location":"Advanced/sunshine-brew/","title":"Changes to Sunshine on Bazzite","text":"<p>This change will take effect in an update in the near future, along with the switch to OGC kernel with inputplumber. Look out for announcements!</p>"},{"location":"Advanced/sunshine-brew/#the-change","title":"The Change","text":"<p>Sunshine had historically been shipped with the base Bazzite image - but that will no longer be the case. </p>"},{"location":"Advanced/sunshine-brew/#why-is-this-happening","title":"Why is this happening?","text":"<p>The reasoning for this change is due to the lack of a stable package of Sunshine on Fedora 43, and as of April, six months into the Fedora 43 lifecycle, and nearing the release of Fedora 44.  This forced Bazzite to use the Sunshine-Beta package instead, and had thus caused users to have non-functional streaming after an update numerous times, due to multiple changes to their systemd service name.</p>"},{"location":"Advanced/sunshine-brew/#what-should-i-do-if-i-am-currently-using-sunshine","title":"What should I do if I am currently using Sunshine?","text":"<p>The guide below will walk you through switching to the Homebrew Sunshine package if you already actively use Sunshine, so that you will continue to have a working stream from your Bazzite Sunshine host when the update occurs.</p> <ol> <li>Open the Bazzite Portal and select Sunshine </li> <li>Select Enable or Enable(Beta) if you want the beta version of Sunshine </li> <li>A Terminal Window will appear. Wait for the installation to complete and you will be prompted to input your password to enable screen capture through Kernel Mode Setting.</li> <li>Disable the old Sunshine service by opening a new terminal window and run  <pre><code>systemctl --user disable --now app-dev.lizardbyte.app.Sunshine.service\n</code></pre> </li> <li>This is a good time to test if your new setup works - Your settings should persist.</li> </ol>"},{"location":"Advanced/sunshine-brew/#something-went-wrong-what-should-i-do","title":"Something went wrong, what should I do?","text":""},{"location":"Advanced/sunshine-brew/#the-brew-link-step-did-not-complete-successfully","title":"<code>The brew link step did not complete successfully</code>","text":"<p> To fix this, make the directory by running  <pre><code>mkdir -p /home/linuxbrew/.linuxbrew/Cellar/xkeyboard-config/2.47/share/xkeyboard-config-2\n</code></pre></p> <p>If you encounter any other issues, feel free to reach out on the Bazzite Discord!</p>"},{"location":"Advanced/swapfile/","title":"Using Swap for Additional Memory or Hibernation","text":""},{"location":"Advanced/swapfile/#purpose","title":"Purpose","text":"<p>This guide will walk you through the steps to create a swapfile on a BTRFS filesystem, which can be used for additional memory or hibernation.</p> <p>Bazzite-Deck images already support hibernation via Handheld Daemon using a dynamic swap file (<code>General -&gt; Hibernate</code>). In addition, all Bazzite images use zram by default to provide additional memory.</p> <p>Use this guide if you want to create a persistent swapfile instead of zram for more uncompressed memory, or if you want to use hibernation via the desktop environment. </p>"},{"location":"Advanced/swapfile/#create-the-swapfile","title":"Create the Swapfile","text":"<p>First, create a subvolume for the swapfile. This ensures that if you decide to use snapshots, the swapfile will not be included in them. You should also fix the SELinux context of the swapfile directory. <pre><code>sudo btrfs subvolume create /var/swap\nsudo semanage fcontext -a -t var_t /var/swap\nsudo restorecon /var/swap\n</code></pre></p> <p>Then, create the swapfile itself. In this example, we create a 26GB swapfile. Again, you need to fix the SELinux context of the swapfile itself. <pre><code>SIZE=26G\nsudo btrfs filesystem mkswapfile --size $SIZE /var/swap/swapfile\nsudo semanage fcontext -a -t swapfile_t /var/swap/swapfile\nsudo restorecon /var/swap/swapfile\n</code></pre></p> <p>Load the swapfile to verify it works with: <pre><code>sudo swapon /var/swap/swapfile\n</code></pre></p>"},{"location":"Advanced/swapfile/#adding-it-to-fstab","title":"Adding it to fstab","text":"<p>Now, you need to add your swapfile to <code>/etc/fstab</code> to make it persistent: <pre><code>sudo cp /etc/fstab /etc/fstab.bak\nsudo nano /etc/fstab\n</code></pre></p> <p>Attention</p> <p>Be careful when you edit the fstab file otherwise your system will no longer start! In this case, the previous image can be used to boot.</p> <p>Add the following line of code to fstab:</p> <pre><code>/var/swap/swapfile none swap defaults,nofail 0 0\n</code></pre>"},{"location":"Advanced/swapfile/#disable-zram","title":"Disable zram","text":"<p>Finally, you need to disable zram to enable hibernation to work properly. For this, you can zero out the zram-generator configuration file. This prevents Bazzite updates from restoring it. <pre><code>echo \"\" | sudo tee /etc/systemd/zram-generator.conf\n</code></pre></p> <p>Finally, reboot your device to apply the changes made above.</p>"},{"location":"Advanced/swapfile/#reverting-changes-and-restoring-zram","title":"Reverting Changes and Restoring zram","text":"<p>To revert the changes and restore zram, first remove the swapfile entry from <code>/etc/fstab</code>. Then, re-enable zram by copying the original configuration file back: <pre><code>sudo cp /usr/etc/systemd/zram-generator.conf /etc/systemd/zram-generator.conf\n</code></pre></p>"},{"location":"Gaming/","title":"Gaming Guides","text":"<ul> <li>Introduction to Gaming on Bazzite</li> <li>Hardware Compatibility for Gaming</li> <li>Game Launchers</li> <li>Managing &amp; Modding Games</li> <li>Launch Options and Environment Variables</li> <li>Common Gaming Issues</li> </ul>"},{"location":"Gaming/Common_gaming_issues/","title":"Common Gaming Issues","text":""},{"location":"Gaming/Common_gaming_issues/#native-linux-port-versus-windows-version","title":"Native Linux Port Versus Windows Version","text":"<p>Some Linux ports may have missing functionality or worse performance than on the Windows version running through Proton. However, there are scenarios where using the native port exclusively is your only option, and may even be desirable.  </p> <p>If a Linux native game does not launch, then force the Legacy Runtime compatibility layer by going into the game's properties and selecting \"Compatibility\" then checking \"Force the use of a specific Steam Play compatibility tool\" and selecting it.</p>"},{"location":"Gaming/Common_gaming_issues/#denuvo-anti-tamper-drm-locking-games","title":"Denuvo Anti-Tamper DRM Locking Games","text":"<p>Games that use Denuvo Anti-Tamper DRM consider changing Proton versions as activating the game on different hardware which may cause you to get locked out of the game if you change the Proton version more than 5 times within a 24 hour period.</p>"},{"location":"Gaming/Common_gaming_issues/#source-1-engine-audio-and-custom-content-bugs","title":"Source 1 Engine Audio and Custom Content Bugs","text":"<p>Note</p> <p>This only applies to specific games running on the Source engine.</p> <p>Attention</p> <p>Do not attempt to follow this workaround until you run into issues with audio or the specific scenario mentioned below regarding Left 4 Dead 2.</p> <p>Missing voice lines or custom content not loading in Source games? SELinux is blocking MP3 decoding and other middleware because it executes heap memory.</p> <p>This has also been confirmed to cause issues joining and hosting custom maps in Left 4 Dead 2.</p>"},{"location":"Gaming/Common_gaming_issues/#the-fix-for-audiocustom-content-issues","title":"The fix for audio/custom content issues:","text":"<p>Warning</p> <p>Configuring SELinux is intended for advanced users and if used irresponsibly can break other components in your system and weaken the security of your device.</p> <p>Open a host terminal and enter these 4 commands at your own risk:</p> <pre><code>sudo su\n</code></pre> <pre><code>cd /tmp\n</code></pre> <pre><code>ausearch -c 'hl2_linux' --raw | audit2allow -M my-hl2linux\n</code></pre> <pre><code>semodule -X 300 -i my-hl2linux.pp\n</code></pre> <p>Reboot your device and test to see if the Source game still has issues.</p>"},{"location":"Gaming/Common_gaming_issues/#undoing-this-change","title":"Undoing this change:","text":"<p>Disable or remove the module.</p>"},{"location":"Gaming/Common_gaming_issues/#disable-the-change","title":"Disable the change:","text":"<pre><code>semodule -X 300 -d my-hl2linux\n</code></pre>"},{"location":"Gaming/Common_gaming_issues/#remove-and-delete-the-change","title":"Remove and delete the change:","text":"<pre><code>semodule -X 300 -r my-hl2linux\n</code></pre> <p>The <code>.pp</code> file should be in <code>/root</code> if you want to remove that.</p>"},{"location":"Gaming/Common_gaming_issues/#steam-games-not-launching","title":"Steam Games Not Launching","text":"<p>Steam games might not launch for a variety of reasons.</p>"},{"location":"Gaming/Common_gaming_issues/#gathering-steam-log-files","title":"Gathering Steam log files:","text":"<p>If you encounter issues with a game launching on Steam:</p> <ol> <li> <p>Open the game's properties and enter this launch option: <code>PROTON_LOG=1 %command%</code></p> </li> <li> <p>Launch the game</p> </li> </ol> <p>A log file should appear in your Home directory named after the game's application ID number.</p>"},{"location":"Gaming/Common_gaming_issues/#ntfs-formatted-drive-permission-issues","title":"NTFS formatted drive permission issues:","text":"<p>Make sure your games are not on a NTFS (Windows) partition. More information can be found here.</p>"},{"location":"Gaming/Common_gaming_issues/#multi-user-wine-quirks","title":"Multi-user WINE quirks:","text":"<p>Note</p> <p>Bazzite-Deck does not support multiple Linux user accounts, this information only applies to the Desktop edition of Bazzite.</p> <p>Sometimes Steam games will completely refuse to launch on a secondary user account. This can be due to the ownership of the WINE prefix files. You might see an error like this in <code>~/.local/share/Steam/logs/console-linux.txt</code> on the secondary user account:</p> <pre><code>wineserver: /SteamLibrary/steamapps/compatdata/377160/pfx is not owned by you\n</code></pre> <p>You can fix this by creating a separate Steam library folder to hold the prefix data for Proton and creating a symbolic link (symlink) for the other folders (like common game data).</p> <pre><code>USER2@bazzite: /mnt/ExtraStuff/USER2SteamLibrary/steamapps$ ls -la\ntotal 32\ndrwxrwxr-x. 3 USER2 steamplayers 4096 Jan 29 15:19 .\ndrwxrwsr-x. 3 USER2 steamplayers 4096 Jan 29 16:13 ..\n-rwxr-xr-x. 1 USER2 USER2         2287 Jan 29 15:19 appmanifest_377160.acf\nlrwxrwxrwx. 1 USER2 USER2           51 Jan 29 15:10 common -&gt; /mnt/ExtraStuff/USER1SteamLibrary/steamapps/common/\ndrwxr-xr-x. 3 USER2 USER2         4096 Jan 29 15:13 compatdata\nlrwxrwxrwx. 1 USER2 USER2           56 Jan 29 15:12 shadercache -&gt; /mnt/ExtraStuff/USER1SteamLibrary/steamapps/shadercache/\nlrwxrwxrwx. 1 USER2 USER2           49 Jan 29 15:12 temp\nlrwxrwxrwx. 1 USER2 USER2           53 Jan 29 15:12 workshop\n</code></pre> <p>Similarly copy or symlink the appmanifest files from each library for games to show up properly in each Steam library. </p>"},{"location":"Gaming/Game_Launchers/","title":"Game Launchers","text":""},{"location":"Gaming/Game_Launchers/#steam-setup","title":"Steam Setup","text":"<p>Steam can run Windows games on Linux. It utilizes a wide range of projects and patches all packed into a piece of software built-in to Steam called Proton for Windows compatibility.</p>"},{"location":"Gaming/Game_Launchers/#forcing-a-specific-proton-steam-play-tool-version","title":"Forcing A Specific Proton / Steam Play Tool Version","text":""},{"location":"Gaming/Game_Launchers/#important-notes","title":"Important Notes","text":"<ul> <li>Games with a Linux port will be used by default on Desktop images.</li> <li>Valve selects the default runner on Handheld/HTPC images. </li> <li>Some games run better with a specific version of Proton or forcing the Linux runtime to run the Linux port.</li> </ul> <p>Run that specific version by going into the game's Properties &gt; Compatibility &gt; Force the use of a specific Steam Play compatibility tool</p>"},{"location":"Gaming/Game_Launchers/#image-example","title":"Image Example","text":""},{"location":"Gaming/Game_Launchers/#non-steam-games","title":"Non-Steam Games","text":"<p>It is recommended to use Lutris for most non-steam games.  There are edge cases with specific launchers and games that have a better working alternative than Lutris, but Lutris is the most supported option for PC games outside of Steam on Bazzite outside of special scenarios.</p>"},{"location":"Gaming/Game_Launchers/#lutris-setup","title":"Lutris Setup","text":"<p>Lutris offers two methods to play Windows games on Bazzite.  Community-driven scripts or manually adding the executable.  It is highly recommended to use the manual method as some scripts are poorly maintained.</p>"},{"location":"Gaming/Game_Launchers/#manually-adding-a-windows-game-to-lutris","title":"Manually adding a Windows game to Lutris","text":"<p>However if your game is not listed or doesn't work with the provided script, then manually add the executable. It will need a prefix directory created, but by default it will use the <code>~/Games</code> directory for each game.</p>"},{"location":"Gaming/Game_Launchers/#lutris-install-scripts","title":"Lutris Install Scripts","text":"<p>Lutris is game management software that doubles as a WINE front-end for Windows games. Several games and launchers can be installed by searching for the title and using one of the installer scripts for it. </p>"},{"location":"Gaming/Game_Launchers/#lutris-shortcuts","title":"Lutris Shortcuts","text":"<p>Right clicking a game on Lutris gives the option to add it as a non-Steam game (useful for Steam Gaming Mode), create a desktop shortcut, or an application menu shortcut.</p>"},{"location":"Gaming/Game_Launchers/#other-game-launchers","title":"Other Game Launchers","text":"<p>Bazaar can install other game launchers like Heroic Games Launcher (for GOG/Epic/Amazon games) or alternate frontends like Faugus.</p>"},{"location":"Gaming/Hardware_compatibility_for_gaming/","title":"Hardware Compatibility for Linux Gaming","text":""},{"location":"Gaming/Hardware_compatibility_for_gaming/#minimum-system-requirements","title":"Minimum System Requirements","text":"<ul> <li>Architecture: x86_64</li> <li>Firmware: UEFI (CSM/Legacy boot UNSUPPORTED)</li> <li>Processor (CPU) : 2GHz quad core processor or better</li> <li>System Memory (RAM): 8GB</li> <li>Graphics: A graphics card that can utilize Vulkan 1.3 or higher, modern AMD GPUs work the best</li> <li>Storage: 50GB of free space on an internal solid-state drive (SSD)<ul> <li>Recommended Storage: 120GB of free space on an internal solid-state drive (SSD)</li> <li>External Storage &amp; Secondary Drives: All drives must be formatted as BTRFS (SSDs) or Ext4 (Hard Disk Drives [HDDs]) (please backup the files and reformat them post-installation)</li> </ul> </li> <li>Network: Stable internet connection with no bandwidth caps (not required for installation)</li> <li>Additional Notes: Certain peripherals are not compatible with Bazzite:<ul> <li>Wi-Fi Adapter Example - a list of known compatible USB Wi-Fi adapters</li> </ul> </li> </ul> <p>The Hardware for Linux website is a good indicator for how well OEM hardware is supported on the Linux desktop.</p>"},{"location":"Gaming/Hardware_compatibility_for_gaming/#steam-gaming-mode-requirements","title":"Steam Gaming Mode Requirements","text":"<p>Note</p> <p>These specific requirements only apply to Bazzite-Deck images which ships with all handheld Bazzite ISO downloads.</p> <ul> <li>Modern AMD GPU<ul> <li>RX 4xx series and up<ul> <li>600M/700M integrated GPUs are also supported</li> </ul> </li> </ul> </li> <li>Intel Arc GPUs are supported with minor caveats compared to AMD hardware</li> <li>Nvidia GPU support is supported with major caveats compared to AMD hardware out of control of the Bazzite maintainers</li> <li>Requires a Steam account<ul> <li>Signing up for an account can be done post-installation if you don't have one already</li> </ul> </li> </ul> <p>The Hardware for Linux website is a good indicator for how well OEM hardware is supported on the Linux desktop.</p>"},{"location":"Gaming/Hardware_compatibility_for_gaming/#compatible-handhelds","title":"Compatible Handhelds","text":"<p>The Handheld Wiki lists tested handhelds with proper support for the Steam Deck, ASUS ROG Ally, Lenovo Legion Go, and a handful of other handhelds.</p>"},{"location":"Gaming/Hardware_compatibility_for_gaming/#vulkan-compatible-gpu","title":"Vulkan Compatible GPU","text":"<p>Attention</p> <p>Linux gaming is heavily dependent on having compatible hardware with Vulkan.</p>"},{"location":"Gaming/Hardware_compatibility_for_gaming/#viewing-your-gpus-vulkan-version","title":"Viewing Your GPU's Vulkan Version","text":"<p>If you're using a device with an older or weaker GPU that does not support Vulkan 1.3 or later, then you need to use older Proton and Wine builds like Proton/WINE 6 or earlier.  Check which Vulkan version your GPU uses, enter this in the terminal:</p> <pre><code>vulkaninfo | grep 'Instance Version'\n</code></pre> <ul> <li>If it outputs less than <code>1.3</code> in the <code>Vulkan Instance Version:</code> or does not work at all, then you will run into issues including unplayable games and worse performance.</li> <li>Really old devices may need to resort to OpenGL translation which performs worse, has graphical issues, etc.</li> </ul> <p></p> <p>Try using Proton-Sarek if your have hardware that can utilize Vulkan 1.1, but not newer Vulkan versions. It can be installed using ProtonPlus.</p>"},{"location":"Gaming/Hardware_compatibility_for_gaming/#gpus-without-vulkan-support","title":"GPUs Without Vulkan Support","text":"<p>However if your GPU does not support Vulkan at all then you must use an older Proton version (Proton 3, 4, or 5) and use this launch option for most Steam games:</p> <pre><code>PROTON_USE_WINED3D=1 %command%\n</code></pre> <p>This will use the OpenGL translation as opposed to Vulkan.</p>"},{"location":"Gaming/Hardware_compatibility_for_gaming/#storage-filesystems","title":"Storage Filesystems","text":"<p>Note</p> <p>Bazzite will automatically mount secondary drives that are formatted as Ext4 or BTRFS by default.</p> <p>BTRFS is the default and recommended filesystem for Bazzite.  Any secondary drives that you plan to play video games on should be backed up and reformatted to either Ext4 or BTRFS, however the drive will lose all of the data when performing this operation.  You can use GNOME Disks to format the drives appropriately at your own risk.</p>"},{"location":"Gaming/Hardware_compatibility_for_gaming/#unsupported-filesystems-for-secondary-drives","title":"Unsupported Filesystems for Secondary Drives","text":"<p>Critical</p> <p>NTFS and exFAT/FAT32 ARE NOT SUPPORTED. BOTH FILESYSTEMS CAN AND WILL LEAD TO DATA CORRUPTION UNDER LINUX. DO NOT USE THEM! winBTRFS UNDER WINDOWS STILL HAS BUGS AND IS ALSO NOT A SOLUTION. </p> <p>THERE IS CURRENTLY NO RELIABLE CROSS-PLATFORM FILESYSTEM THAT CAN BE SHARED WITH WINDOWS AND LINUX.</p> <p>Warning</p> <p>You will lose all of your data reformatting secondary internal/external drives.</p> <p>Info</p> <p>To disable the NTFS nag, run <code>ujust _disable-ntfs-service</code>. ONLY DO THIS IF YOU KNOW WHAT YOU ARE DOING. THIS WILL NOT PREVENT DATA LOSS, ONLY DISABLE THE WARNING.</p>"},{"location":"Gaming/Hardware_compatibility_for_gaming/#ntfs","title":"NTFS","text":"<p>If you are coming from Windows and plan to game on a secondary drive with games already installed on it, then we regret to inform you that the NTFS filesystem is unsupported for PC gaming on Bazzite.</p> <p>Playing games off of NTFS causes various issues, including but not limited to games not launching at all, and will eventually result in data corruption and permanent data loss!</p>"},{"location":"Gaming/Hardware_compatibility_for_gaming/#exfat-and-fat32","title":"exFAT and FAT32","text":"<p>FAT32 and exFAT are unsupported. Both filesystems do not support symbolic links which is required for Proton prefixes to work properly.  However, there are scenarios where a microSD card is formatted to exFAT may work in some cases, but this method is unsupported as something the Bazzite maintainers do not plan to accommodate.</p>"},{"location":"Gaming/Hardware_compatibility_for_gaming/#sharing-games-with-a-windows-dual-boot","title":"Sharing Games with a Windows Dual-Boot","text":"<p>Install the unofficial WinBtrfs driver on your Windows installation at your own risk. Please make sure to read any documentation associated with this project before installing the driver on Windows.</p>"},{"location":"Gaming/Hardware_compatibility_for_gaming/#video-tutorial","title":"Video Tutorial","text":""},{"location":"Gaming/Managing_and_modding_games/","title":"Managing and Modding Games","text":""},{"location":"Gaming/Managing_and_modding_games/#compatibility-layers-managing-windows-games","title":"Compatibility Layers &amp; Managing Windows Games","text":"<p>Windows games need to run through a compatibility layer (like Proton) on Bazzite. Install and update to the latest GE-Proton, Luxtorpeda, and other tools using ProtonPlus.</p>"},{"location":"Gaming/Managing_and_modding_games/#protontricks","title":"Protontricks","text":"<p>Some games require Protontricks (pre-installed) or Winetricks (for non-Steam games, included with Lutris) to function properly by installing Windows DLLs into the prefix.</p>"},{"location":"Gaming/Managing_and_modding_games/#hidden-files-in-file-manager","title":"Hidden Files in File Manager","text":"<p>Note</p> <p>Winecfg contains the option to show hidden files for Windows programs that require the filepicker.</p> <p>Desktop Linux contains hidden files and directories that may include important files related to gaming.</p> <p>Show hidden files by clicking the hamburger menu (3 horizontal lines in the file manager) and selecting \"Show Hidden Files\" to see every directory and file that is hidden by default.</p> <p>These directories and files all start with a <code>.</code> before it</p>"},{"location":"Gaming/Managing_and_modding_games/#what-is-a-proton-or-wine-prefix","title":"What is a Proton (or Wine) Prefix?","text":"<p>It's the glue that holds everything together when you run a game through Proton and also is responsible for containing any of the files the game would drop outside of the installation folder.</p> <p>Important</p> <p>This installation folder for Steam games is usually in: <code>.../steamapps/common/&lt;game&gt;</code></p> <p>Many PC games drop files in Windows folders like \"My Documents\" or \"AppData\" and both can be found in your prefix directory. This prefix directory may be useful for modding your games, backing up your saves, or configuration files.</p> <p></p> <p>For games on Steam, they are located in your <code>~/.steam/root/steamapps/compatdata/</code> folder, and then the AppID number of the game:</p> <ul> <li>This ID by going into the game's properties on Steam in the games Properties &gt;&gt; Updates &gt;&gt; App ID</li> <li>Continue to <code>.../pfx/drive_c/</code> and wherever the game drops the file on Windows.</li> </ul> <p>Non-Steam games can have the prefix folder anywhere you specify.  By default Lutris uses <code>~/Games</code> as the main folder.</p>"},{"location":"Gaming/Managing_and_modding_games/#broken-proton-prefix","title":"Broken Proton Prefix?","text":"<p>Warning</p> <p>Deleting a Proton prefix can delete saves and configuration files!</p> <p>Open the prefix directory for the game and delete the data inside of it. Be careful not to delete the root <code>.../compatdata</code> directory (or <code>~/Games</code>, or the custom directory that you set, for non-Steam games) which would remove the prefix data for all of the games!</p>"},{"location":"Gaming/Managing_and_modding_games/#modding","title":"Modding","text":"<p>Steam Workshop is the most straightforward method to obtain mods, but is not supported for every title and requires you to own the game on Steam. Some mod managers have Linux ports like r2modman.</p> <p>Adding and replacing game files is still viable in both the game directory and prefix, but there may be some extra steps involved.  Some mods require a \"WINE DLL OVERRIDE\" environment variable in the Steam launch options.  For non-Steam Games, use Lutris to open \"Wine Configuration\" and select the \"Libraries\" tab to add new overrides.</p>"},{"location":"Gaming/Managing_and_modding_games/#example-of-a-dll-override-launch-option","title":"Example of a DLL override launch option:","text":"<pre><code>**DirectInput8 DLL Override**: \n`WINEDLLOVERRIDES=\"dinput8=n,b\" %command%`\n</code></pre>"},{"location":"Gaming/gaming-intro/","title":"Introduction to Gaming on Bazzite","text":""},{"location":"Gaming/gaming-intro/#paradigm-shift","title":"Paradigm Shift","text":"<p>Linux gaming being a viable competitor to Windows is a relatively new paradigm. Most Windows exclusive games can run on Bazzite using modern hardware. There are still some rough edges, but gaming on Linux does offer advantages on the appropriate hardware such as better frame-times than on Windows.</p>"},{"location":"Gaming/gaming-intro/#steam-games","title":"Steam Games","text":"<p>Steam is the recommended way to play PC games on Bazzite as it ships with a compatibility layer known as Proton,  which is a fork of WINE and other various projects merged into a convenient runner built into Steam for Linux, that is intended for gaming developed by Valve. Most singleplayer PC games should be able to run without any tweaking necessary, but there are cases where a game purchased and installed through Steam will not run out of the box.  Some newer online multiplayer games require deeper access to your computer hardware and Windows drivers to run their anti-cheat software which may not run on Bazzite meaning these games will be unplayable unless Windows is running.</p>"},{"location":"Gaming/gaming-intro/#non-steam-games","title":"Non-Steam Games","text":"<p>Bazzite can also run games off of Steam using Lutris, which is a frontend for running video games and other software through Proton/WINE. Faugus Launcher is an alternative to Lutris available in the Bazaar app store which may be favorable due to a simpler design than Lutris. Heroic Games Launcher is recommended over Lutris for games that were purchased from Epic Games Launcher, GOG, and Amazon Games Launcher.  </p> <p>Games installed from the Microsoft Store do not run unless you use a Xbox Cloud Gaming client like Greenlight which requires a Game Pass Ultimate subscription for most games. Fortnite can also be played via this method without a Game Pass subscription.  There are also select Game Pass titles available on Battle.net which can be ran using Lutris.  </p> <p>Console emulators can be installed from Bazaar or through projects like Retrodeck or Emudeck (Available in the Bazzite Portal application).</p>"},{"location":"Gaming/gaming-intro/#useful-external-resources","title":"Useful External Resources","text":"<ul> <li>ProtonDB - User reports for game compatibility on Linux</li> <li>Are We Anti-Cheat Yet? - List of popular games utilizing anti-cheat software and if the game supports Linux</li> <li>Linux Gaming Wiki - Introduction to Linux gaming that includes helpful links</li> <li>PC Gaming Wiki - General information, workarounds, and enhancements for PC games</li> <li>General Emulation Wiki - Emulation resources</li> <li>Linux VR Adventures Wiki - General information for running VR games on Linux</li> <li>Linux VR Adventure Database - User reports for Virtual Reality (VR) game compatibility on Linux</li> </ul>"},{"location":"Gaming/launch-options-env-variables/","title":"Launch Options and Environment Variables","text":""},{"location":"Gaming/launch-options-env-variables/#preface","title":"Preface","text":"<p>Linux gaming is far more intuitive today than it was years ago.  There are still advanced launch options and configurations that can be ran from Bazzite though.  This guide will show off examples of advanced gaming tweaks that can be done on a Bazzite installation.</p>"},{"location":"Gaming/launch-options-env-variables/#configuration-templates-for-dxvk-mangohud-vkbasalt","title":"Configuration Templates for DXVK, MangoHud, &amp; vkBasalt","text":"<p>Bazzite users can use templates for some of the pre-installed tools which can be accessed by right clicking anywhere in the file manager.  There are also applications like Mango Juice that acts as a graphical method of configuring Mangohud.</p>"},{"location":"Gaming/launch-options-env-variables/#steam-launch-options-and-shortcuts","title":"Steam Launch Options and Shortcuts","text":"<p>Steam launch options allow you to pass environment variables, arguments, and commands to games when they start. Bazzite includes several shortcuts and UX improvements to make common launch options easier to use, especially on handheld devices.</p>"},{"location":"Gaming/launch-options-env-variables/#common-launch-option-patterns","title":"Common Launch Option Patterns","text":"<p>Most Steam launch options follow this pattern: <code>ENVIRONMENT_VARIABLES command_or_script %command%</code></p> <ul> <li><code>%command%</code> represents the game executable and must be included</li> <li>Environment variables go before <code>%command%</code></li> <li>Additional arguments can go after <code>%command%</code></li> </ul> <p>Examples: <pre><code>PROTON_LOG=1 %command%                    # Enable Proton logging\nSteamDeck=0 %command%                     # Disable Steam Deck mode\nPROTON_ENABLE_NGX_UPDATER=1 %command%     # Enable DLSS updates\n</code></pre></p>"},{"location":"Gaming/launch-options-env-variables/#bazzites-launch-option-shortcuts","title":"Bazzite's Launch Option Shortcuts","text":"<p>Bazzite includes several shortcuts to simplify common launch options:</p>"},{"location":"Gaming/launch-options-env-variables/#for-steam-deck-mode-control","title":"For Steam Deck Mode Control","text":"<ul> <li><code>sd0 %command%</code> - Shorthand for <code>SteamDeck=0 %command%</code><ul> <li>Disables Steam Deck specific features that may conflict with your setup</li> <li>Example: Expedition 33 hides most graphics settings unless you set <code>SteamDeck=0</code>, and enforces lower than lowest settings.</li> </ul> </li> </ul>"},{"location":"Gaming/launch-options-env-variables/#for-nvidia-users-dlss-swapper","title":"For NVIDIA Users (dlss-swapper)","text":"<ul> <li><code>dlss-swapper %command%</code> - Enables latest DLSS presets with NGX updater<ul> <li>Replaces: <code>PROTON_ENABLE_NGX_UPDATER=1 DXVK_NVAPI_DRS_SETTINGS=NGX_DLSS_SR_OVERRIDE=on,NGX_DLSS_RR_OVERRIDE=on,NGX_DLSS_FG_OVERRIDE=on,NGX_DLSS_SR_OVERRIDE_RENDER_PRESET_SELECTION=render_preset_latest,NGX_DLSS_RR_OVERRIDE_RENDER_PRESET_SELECTION=render_preset_latest %command%</code></li> </ul> </li> <li><code>dlss-swapper-dll %command%</code> - Same as above but skips NGX updater</li> </ul>"},{"location":"Gaming/launch-options-env-variables/#where-to-set-launch-options","title":"Where to Set Launch Options","text":"<ol> <li>Right-click game in Steam library</li> <li>Select Properties</li> <li>In the General tab, find Launch Options field</li> <li>Enter your launch options</li> </ol>"},{"location":"Gaming/launch-options-env-variables/#frame-rate-limiting-issues-and-inconsistency","title":"Frame Rate Limiting Issues and Inconsistency","text":"<p>When using Gamescope, framerate limits can be applied in several ways. Unfortunately not all methods work for every enviroment, game, or hardware configuration.</p> <p>Many inconsistencies can be observed, especially when applying framerate limits in desktop mode.</p> <p>The tables below show the behavior of different framerate limiting methods.</p>"},{"location":"Gaming/launch-options-env-variables/#steam-game-mode-steam-gaming-mode-session","title":"Steam Game Mode (Steam Gaming Mode Session)","text":"Method Setup steps Requires V-Sync On In-Game? Change limit without restarting game? Latency Preferred Notes Gamescope FPS limiter Use Quick Access Menu &gt; Performance &gt; Framerate Limit No Yes Meh Preferred Automatically turns v-sync on at driver-level whenever the framerate cap is enabled. Additional latency will be introduced. MangoAPP (embedded) N/A - doesn't work at all. - - - \u2013 Frame limiter settings from mangoapp are ignored in game mode/deck mode. Use the slider or external mangohud instead. MangoHUD (external) Launch Options: <code>MANGOHUD=1 %command%</code> No Yes Meh \u2013 Set <code>fps_limit=0,30,60,120...</code> (0=no cap) in MangoHud.conf. May clash with MangoAPP. DXVK/VKD3D runtime frame limiter DXVK (D3D8/9/10/11): <code>DXVK_FRAME_RATE={fps} %command%</code>VKD3D-Proton (D3D12): <code>VKD3D_FRAME_RATE={fps} %command%</code> No No Best \u2013 Applies only to DXVK/VKD3D titles (no effect on native OpenGL or native Vulkan)."},{"location":"Gaming/launch-options-env-variables/#desktop-mode-gnome-kde-plasma-desktop-session","title":"Desktop Mode (GNOME / KDE Plasma Desktop Session)","text":"Method Setup steps Requires V-Sync On In-Game? Change limit without restarting game? Latency Preferred Notes Gamescope FPS limiter Launch Options: <code>gamescope -r {fps} -- %command%</code> / <code>--framerate-limit {fps}</code> Yes Yes Meh \u2013 Use <code>gamescopectl debug_set_fps_limit {fps}</code> to change the limiter value live without restarting. MangoAPP (embedded) Launch Options: <code>gamescope --mangoapp -- %command%</code> Yes Yes Meh \u2013 Caps are sometimes not effective. Set <code>fps_limit=0,30,60,120...</code> (0=no cap) in MangoHud.conf (or via <code>MANGOHUD_CONFIG=...</code>). Add <code>show_fps_limit</code> to preset to see in game. Change with <code>ShiftL+F1</code>. MangoHUD (external) Launch Options: <code>MANGOHUD=1 gamescope -- %command%</code> No Yes Meh Preferred Caps are almost always effective. Set <code>fps_limit=0,30,60,120...</code> (0=no cap) in MangoHud.conf (or via <code>MANGOHUD_CONFIG=...</code>). Add <code>show_fps_limit</code> to preset to see in game. Change with <code>ShiftL+F1</code>. DXVK/VKD3D runtime frame limiter DXVK (D3D8/9/10/11): <code>DXVK_FRAME_RATE={fps} %command%</code>VKD3D-Proton (D3D12): <code>VKD3D_FRAME_RATE={fps} %command%</code> No No Best \u2013 In-process/API-level caps; excellent timing, but you must restart to change. <p>If your framerate limiter isn't working, the following steps can often help:</p> <ol> <li>Disable adaptive sync/VRR or remove the <code>--adaptive-sync</code> flag from your gamescope args.</li> <li>Set vsync in-game to \"on\".</li> </ol>"},{"location":"Gaming/launch-options-env-variables/#advanced-launch-option-management-for-scopebuddy","title":"Advanced Launch Option Management for ScopeBuddy","text":"<p>For users who need more complex launch option management, consider the ScopeBuddy documentation for even more advanced Gamescope launch option management.</p>"},{"location":"General/","title":"General Guides","text":"<ul> <li>Dictionary &amp; Terminology</li> <li>Comparison of Bazzite and Fedora Atomic Desktop</li> <li>SteamOS Comparison</li> <li>Desktop Environment Tweaks</li> <li>VPN Setup</li> <li>Issues &amp; Resolution</li> <li>Reporting Bugs</li> <li>Community Resources</li> <li>Security Policy</li> <li>License</li> <li>Press Kit</li> <li>Uninstalling Bazzite</li> </ul>"},{"location":"General/Desktop_Environment_Tweaks/","title":"Desktop Environment Customization, Themes, and Tweaks","text":"<p>Warning</p> <p>Install desktop customization software at your own risk!</p>"},{"location":"General/Desktop_Environment_Tweaks/#customizing-kde-plasma-with-themes","title":"Customizing KDE Plasma with Themes","text":"<p>KDE Plasma is the default Bazzite desktop environment and is highly customizable. One of the various customization that can be done is installing custom styles, cursors, and icons to your system with custom themes made by the community.  Themes installed through the System Settings are installed into <code>~/.local/share/plasma</code>; to uninstall them, you may need to manually delete the folders associated with the installed themes manually.</p> <p></p>"},{"location":"General/Desktop_Environment_Tweaks/#manually-installing-themes","title":"Manually Installing Themes","text":"<p>Step-by-step instructions to install custom themes on KDE Plasma.</p> <ol> <li>Download the theme manually from the KDE Store.</li> <li>Extracting the contents to <code>~/.local/share/plasma/</code> (You may need to make this directory.)</li> <li>Open the system settings and select your theme, style, cursor etc. as it now should appear.</li> </ol>"},{"location":"General/Desktop_Environment_Tweaks/#theme-extraction-locations","title":"Theme Extraction Locations","text":"<p>The location where specific KDE Plasma components will be extracted on the desktop.</p>"},{"location":"General/Desktop_Environment_Tweaks/#global-themes","title":"Global Themes","text":"<p>Global themes are placed in <code>~/.local/share/plasma/look-and-feel/</code>. (You may need to make this directory.)</p>"},{"location":"General/Desktop_Environment_Tweaks/#plasma-themes","title":"Plasma Themes","text":"<p>\"Plasma themes\" are placed in <code>~/.local/share/plasma/desktoptheme/</code>. (You may need to make this directory.)</p>"},{"location":"General/Desktop_Environment_Tweaks/#plasma-window-decorations","title":"Plasma Window Decorations","text":"<p>\"Window decoration themes\" are placed in <code>~/.local/share/aurorae/themes/</code>. (You may need to make this directory.)</p>"},{"location":"General/Desktop_Environment_Tweaks/#icon-cursor-themes","title":"Icon / Cursor Themes","text":"<p>\"Icon/Cursor themes\" are placed in <code>~/.local/share/icons</code>. (You may need to make this directory.)</p>"},{"location":"General/Desktop_Environment_Tweaks/#sounds","title":"Sounds","text":"<p>System sounds can be replaced in <code>~/.local/share/sounds</code>. (You may need to make this directory.)</p>"},{"location":"General/Desktop_Environment_Tweaks/#sddm-login-manager-themes","title":"SDDM (Login Manager) Themes","text":"<p>SDDM themes can be layered at your own risk if they are available as RPM packages using <code>rpm-ostree</code>.</p>"},{"location":"General/Desktop_Environment_Tweaks/#application-permissions-to-use-themes","title":"Application Permissions to Use Themes","text":"<p>Some Flatpaks need filesystem permissions for applications that have issues with cursor themes.</p> <p>Example: (<code>~/.local/share/icons/:ro</code> in \"Filesystem\" in each problematic application or globally in Flatseal).</p>"},{"location":"General/Desktop_Environment_Tweaks/#customizing-other-desktops-and-sessions","title":"Customizing Other Desktops and Sessions","text":"<p>The default desktop environment for Bazzite is KDE Plasma which also happens to offer the most in-depth customization for a modern Linux desktop environment to date which is why this guide focuses heavily on Bazzite images that run KDE Plasma.</p>"},{"location":"General/Desktop_Environment_Tweaks/#manage-gnome-extensions-gnome-images","title":"Manage GNOME Extensions (<code>-gnome</code> Images)","text":"<p>The \"Extension Manager\" application allows for installing new extensions to GNOME and managing currently pre-installed extensions.  Proceed with caution as extensions can make your system unstable and if your desktop crashes then GNOME will disable all of the extensions on the next boot.</p>"},{"location":"General/Desktop_Environment_Tweaks/#steam-gaming-mode-customization-deck-images","title":"Steam Gaming Mode Customization (<code>-deck</code> Images)","text":"<p>Warning</p> <p>Decky Loader will sometimes have issues with new Steam and Gamescope updates, and may need to be uninstalled temporarily.</p> <p>Install Decky Loader then install CSS Loader to customize how Steam Gaming Mode looks. Be aware that third-party plugins may cause issues. Read Bazzite's Steam Gaming Mode quirks documentation to resolve common issues if you run into them after using Decky Loader.</p>"},{"location":"General/Desktop_Environment_Tweaks/#desktop-environment-documentation","title":"Desktop Environment Documentation","text":"<ul> <li>KDE Plasma Documentation</li> <li>GNOME Documentation</li> <li>Bazzite's Steam Gaming Mode Documentation</li> </ul>"},{"location":"General/FAQ/","title":"Frequently Asked Questions (FAQ)","text":""},{"location":"General/FAQ/#who-is-bazzite-for","title":"Who is Bazzite for?","text":"<p>Bazzite is for those seeking an operating system that fits one of the following criteria:</p> <ul> <li>A desktop operating system designed for gaming with inspiration from SteamOS that has fairly low maintenance in comparison to other desktop Linux operating systems.</li> <li>A proper frontend for a controller-friendly experience for couch PC gaming.</li> <li>An alternative to Windows-based handhelds where a SteamOS-like experience is preferable and SteamOS currently does not run well or is missing functionality on the handheld hardware.</li> <li>A SteamOS-like experience on SteamOS handhelds (like the Steam Deck or Lenovo Legion Go S SteamOS Edition) with newer system packages and alternate desktop environments with the same image-based OS approach for stability.</li> </ul>"},{"location":"General/FAQ/#what-bazzite-image-do-i-use","title":"What Bazzite image do I use?","text":"<p>Bazzite's website offers a streamlined way of selecting the correct image which will be chosen based on hardware, desktop environment, and to include Steam Gaming Mode if the hardware supports it.</p> <p>Bazzite offers multiple images, but most images will be following one of these three variants:</p> <ul> <li>Variant 1: Bazzite images that do not have Steam Gaming Mode and receive automatic updates daily with gaming packages pre-installed.</li> <li>Variant 2: Bazzite images that automatically boot into Steam Gaming Mode (like SteamOS) and are intended for controller-oriented setups.</li> <li>Variant 3: Bazzite images that are intended for software development.</li> </ul>"},{"location":"General/FAQ/#1-desktop-edition","title":"1. Desktop Edition","text":"<p><sub>(Variant 1)</sub></p> <p>Steam Gaming Mode is not on these specific images!</p> <p>Intended specifically for desktops and laptops with a focus on gaming which is influenced by SteamOS's Desktop Mode and the maintenance-free nature of ChromeOS. A gaming-focused Fedora Atomic Desktop (Kinoite/Silverblue) operating system.  Steam and other gaming utilities are part of the base operating system. System rollbacks available with a rock-solid stable Fedora Linux base. Most modern PC hardware should be compatible outside of specific drivers that do not work well on desktop Linux.  Flathub is enabled out of the box, so all of the applications that you would find on SteamOS are available on Bazzite.  System and application updates are automatically downloaded in the background and applied on a restart by default.</p>"},{"location":"General/FAQ/#2-bazzite-deck-edition","title":"2. Bazzite-Deck Edition","text":"<p><sub>(Variant 2)</sub></p> <p>\"Steam Gaming Mode\" is pre-installed and its features fully functional for supported hardware. This version of Bazzite boots directly into the Steam Gaming Mode session and is intended for handhelds and couch-gaming scenarios. It also includes a Desktop Mode session. System and application updates are manually upgraded in Steam Gaming Mode and applied on a reboot.</p>"},{"location":"General/FAQ/#3-bazzite-dx-developer-experience-edition","title":"3. Bazzite-DX (Developer eXperience Edition)","text":"<p><sub>(Variant 3)</sub></p> <p>A version of Bazzite that specifically caters to software development. It is not installed via an ISO; instead, you switch to it by rebasing from your current image to a Bazzite-DX image.</p>"},{"location":"General/FAQ/#bazzite-image-chart-example","title":"Bazzite Image Chart Example","text":"<p>Note</p> <p>This does not include all of the Bazzite images.</p> <p>Verify your Bazzite image by entering this command in the terminal:</p> <pre><code>rpm-ostree status\n</code></pre> <p>Important</p> <p>Every Bazzite image should start with <code>ostree-image-signed:docker://ghcr.io/ublue-os/...</code>. <sub> The <code>...</code> is a placeholder for the actual image name which can be referenced in the chart below. </sub></p> Image Desktop Environment Steam Gaming Mode Hardware Edition <code>bazzite</code> KDE Plasma No AMD/Intel GPUs Desktop <code>bazzite-nvidia</code> KDE Plasma No Nvidia GPUs Desktop <code>bazzite-nvidia-open</code> KDE Plasma No Nvidia GPUs (Newer Nvidia GPUs) Desktop <code>bazzite-gnome</code> GNOME No AMD/Intel GPUs Desktop <code>bazzite-gnome-nvidia</code> GNOME No Nvidia GPUs Desktop <code>bazzite-gnome-nvidia-open</code> GNOME No Nvidia GPUs (Newer Nvidia GPUs) Desktop <code>bazzite-deck</code> KDE Plasma Yes AMD/Intel Arc GPUs Bazzite-Deck <code>bazzite-deck-nvidia</code> KDE Plasma Yes Nvidia GPUs (Newer Nvidia GPUs) Bazzite-Deck <code>bazzite-deck-nvidia-gnome</code> GNOME Yes Nvidia GPUs (Newer Nvidia GPUs) Bazzite-Deck <code>bazzite-deck-gnome</code> GNOME Yes AMD/Intel Arc GPUs Bazzite-Deck"},{"location":"General/FAQ/#steamos-is-based-on-arch-linux-so-why-use-fedora-atomic-desktop","title":"SteamOS is based on Arch Linux, so why use Fedora Atomic Desktop?","text":"<p>SteamOS receives package and driver updates less frequently despite the rolling release base.  Bazzite will follow Fedora's update release cycle which means early access to new graphics card driver and kernel updates in comparison to SteamOS.  Fedora Linux and Universal Blue currently supports a specific \"atomic\" implementation to maintain multiple images that can receive all of the same updates at once, which is unlike a derivative Linux distribution.  The goal of Bazzite is to have an operating system ready to game after installing it.</p>"},{"location":"General/FAQ/#what-are-the-advantages-to-using-fedora-atomic-desktop-as-a-base","title":"What are the advantages to using Fedora Atomic Desktop as a base?","text":"<p>Since Bazzite is a custom Fedora Atomic Desktop image, it makes use of read-only root files for stability purposes, and is built as a bootable container image which has advantages such as:</p> <ul> <li>Low risk of an unbootable system</li> <li>Rollback system updates if necessary, and the ability to pin your current deployment as a backup save state without losing user data.</li> <li>Smooth upgrade process from major Fedora point releases.</li> <li>Focus on containerized applications that do not interfere with your host system.</li> </ul> <p>Check out the Universal Blue homepage for more information on what this project is capable of.</p>"},{"location":"General/FAQ/#are-amd-and-intel-graphics-card-drivers-pre-installed","title":"Are AMD and Intel graphics card drivers pre-installed?","text":"<p>Yes and they are updated during a system upgrade when new drivers are available. It is not possible to manually update them separately as they are part of the image.</p>"},{"location":"General/FAQ/#are-nvidia-graphics-card-drivers-pre-installed","title":"Are Nvidia graphics card drivers pre-installed?","text":"<p>Yes, on the Nvidia images and they are updated during a system upgrade when new drivers are available. It is not possible to manually update them. - The legacy (<code>-nvidia</code>) image supports Pascal, Maxwell, and Volta architectures (GTX 900, GTX 1000, Nvidia Titan V, GTX 750 (TI) and GTX 745). - The modern (<code>-nvidia-open</code>) image supports every Nvidia card from the Turing architecture and newer (GTX 16 and all RTX cards).</p>"},{"location":"General/FAQ/#will-support-for-much-older-nvidia-graphics-cards-be-added","title":"Will support for much older Nvidia graphics cards be added?","text":"<p>There are currently no plans to support Kepler and older architectures (Most GTX 700 cards and older) since they are no longer supported by the upstream Nvidia drivers. - You can still install Bazzite, using the open-source nouveau driver.     - However, the performance and stability of this driver lags behind the official Nvidia drivers. - It is not possible to manually install the proprietary Nvidia drivers for your older card in Bazzite. -     You would need a different Linux distribution that allows for such, if you wish to use the proprietary Nvidia drivers for your GPU.</p>"},{"location":"General/FAQ/#what-if-i-change-hardware","title":"What if I change hardware?","text":"<p>Most hardware changes should not require any manual intervention outside of the expectations from that particular hardware which would be OS-agnostic.  However, if you swap from or to a Nvidia GPU, then rebasing will be necessary as a manual intervention to get the appropriate graphics drivers.</p>"},{"location":"General/FAQ/#windows-games-claim-that-my-graphic-drivers-are-outdated-how-do-i-update-them","title":"Windows games claim that my graphic drivers are outdated, how do I update them?","text":"<p> Windows games cannot correctly detect Linux graphics drivers. - Because the version numbers are different between the Windows and Linux drivers, games will occasionally warn you about outdated drivers. - You can safely ignore any such warning. - Please see here for more details.</p>"},{"location":"General/FAQ/#does-bazzite-support-csmlegacy-boot","title":"Does Bazzite support CSM/Legacy Boot?","text":"<p>No. A notification with instructions on turning off CSM will occur when the installer detects Legacy BIOS boot: </p>"},{"location":"General/FAQ/#am-i-able-to-use-amd-fluid-motion-frames","title":"Am I able to use AMD Fluid Motion Frames?","text":"<p>Yes, but only if the game supports it. It's not available globally for every game like on Windows, but: * There may be individual game mods or Decky plugins that mimic similar functionality. * If you own Lossless Scaling on Steam, you can set up a LSFG Vulkan layer with the <code>ujust get-lsfg</code> terminal command.</p>"},{"location":"General/FAQ/#can-i-theme-my-grubbootloader","title":"Can I theme my GRUB/bootloader?","text":"<p>Theming the bootloader (GRUB) is unsupported by Bazzite and can cause critical issues such as your system not booting. Please remove any GRUB themes before reporting issues.</p>"},{"location":"General/FAQ/#can-i-change-the-hostname-of-my-device","title":"Can I change the hostname of my device?","text":"<p>Note</p> <p>Hostnames must be under 20 characters due to a limitation with Distrobox containers.</p> <p>Open the terminal and enter the following command</p> <pre><code>hostnamectl hostname &lt;hostname&gt;\n</code></pre> <p>Specify a hostname where <code>&lt;hostname&gt;</code> is.</p>"},{"location":"General/FAQ/#windows-bootloader-override","title":"I installed Windows but Bazzite won't boot","text":"<p>Flash the Bazzite Live ISO to a thumb drive, and run the Bazzite Bootloader Restoration Tool.</p>"},{"location":"General/FAQ/#can-i-switch-to-a-different-desktop-environment-on-my-current-installation","title":"Can I switch to a different desktop environment on my current installation?","text":"<p><sub> (Example: Swapping from KDE Plasma to GNOME or vice-versa) </sub></p> <p>It is not recommended to switch between desktop environments due to configuration files having different standards which usually lead to broken installations after rebasing to a different Bazzite image with a different desktop environment installed.</p>"},{"location":"General/FAQ/#am-i-able-to-install-this-desktop-environment-or-that-window-manager","title":"Am I able to install this desktop environment or that window manager?","text":"<p>Make your own custom image based off Bazzite with the desktop environment or standalone window manager change that you want.</p>"},{"location":"General/FAQ/#what-is-the-0-and-1-in-the-grub-menu-at-boot","title":"What is the <code>:0</code> and <code>:1</code> in the GRUB menu at boot?","text":"<p>This allows users to rollback a bad system upgrade by selecting the previous deployment.</p> <ul> <li><code>:0</code> = Current deployment/newest update</li> <li><code>:1</code> = Previous deployment/update.</li> </ul> <p>Deployments can also be pinned to rollback for future use, so <code>:2</code>, <code>:3</code>, etc. can also exist as long as you have the storage space for it.</p>"},{"location":"General/FAQ/#why-is-it-called-bazzite","title":"Why is it called Bazzite?","text":"<p>Fedora Linux's Atomic Desktops originally followed a naming scheme based on minerals. Bazzite is a mineral that is known for being strong, lightweight, and is blue.</p>"},{"location":"General/FAQ/#i-have-questions-or-concerns-that-cannot-be-answered-in-the-documentation","title":"I have questions or concerns that cannot be answered in the documentation","text":"<p>Note</p> <p>Search for the appropriate keywords in Bazzite's documentation first before proceeding with the next steps.</p> <p>We strongly urge you to report it to the issue tracker.  Keep in mind that certain areas and topics are out of our control especially when it comes to Nvidia driver problems, game compatibility, or other problems that plague the modern day Linux desktop regardless if you're running Bazzite or another Linux operating system.</p>"},{"location":"General/Fedora_Atomic_Comparison/","title":"Comparison of Bazzite &amp; Upstream Fedora Atomic Desktop","text":""},{"location":"General/Fedora_Atomic_Comparison/#what-is-bazzite","title":"What is Bazzite?","text":"<p>Bazzite is a custom image of Fedora Kinoite (KDE Plasma images) or Fedora Silverblue (GNOME images) which are part of the Fedora Atomic Desktop family with modifications made to try and provide a user friendly experience out of the box with a focus on PC gaming.</p>"},{"location":"General/Fedora_Atomic_Comparison/#key-differences","title":"Key Differences","text":"<p>The following is a list of features Bazzite ships with that differs from upstream Fedora Atomic Desktop operating systems:</p>"},{"location":"General/Fedora_Atomic_Comparison/#less-post-installation-setup","title":"Less Post-Installation Setup","text":"<ul> <li>Better hardware support out of the box from PC hardware to peripheral devices.</li> <li>Multimedia codecs with full support for accelerated video encoding and decoding out of the box.</li> <li>Gaming-focused software pre-installed like Steam and Lutris.</li> <li>Fedora Flatpak remote removed in favor of using the System Flathub remote to have access to more applications by default.</li> </ul>"},{"location":"General/Fedora_Atomic_Comparison/#ease-of-use","title":"Ease of Use","text":"<ul> <li>Convenient <code>ujust</code> scripts by maintainers and contributors of the project.</li> <li>Steam Gaming Mode is setup out of the box and auto-starts on Bazzite-Deck images which are intended for handheld and couch gaming. </li> </ul>"},{"location":"General/Fedora_Atomic_Comparison/#made-with-developers-in-mind","title":"Made with Developers in Mind","text":"<ul> <li>Homebrew is the intended package manager for command-line tools.</li> <li>Distrobox containers grants access to other Linux desktop package managers for specific applications or development environments.</li> <li>Bazzite-DX variant as the defacto Bazzite image for software development.</li> </ul>"},{"location":"General/Fedora_Atomic_Comparison/#extra-enhancements","title":"Extra Enhancements","text":"<ul> <li>Android application support with Waydroid.</li> <li>Firefox is no longer part of the image in favor of the Flatpak version.<ul> <li>Firefox can now be uninstalled as it is not part of the image</li> <li>It also can receive updates faster since it does not rely on system upgrades to update. </li> </ul> </li> <li>Secondary drives that are formatted as BTRFS or Ext4 will be automatically auto-mounted.</li> <li>Tweaks to desktop environments including pre-installed GNOME extensions and KDE Plasma themes.</li> <li>Rollback to older Bazzite builds within the last 90 days.</li> </ul>"},{"location":"General/SteamOS_Comparison/","title":"Comparison of Bazzite and SteamOS","text":""},{"location":"General/SteamOS_Comparison/#what-is-steamos","title":"What is SteamOS?","text":"<p>SteamOS is an operating system originally designed for the Steam Deck. SteamOS is an OS for the Steam client and also features a basic desktop environment with KDE Plasma that allows users to e.g., install mods and emulators, but may be limited for desktop use.</p>"},{"location":"General/SteamOS_Comparison/#what-is-bazzite","title":"What is Bazzite?","text":"<p>Bazzite is a community-driven Linux gaming operating system, featuring the latest Linux drivers and a variety of flavors (Desktop (Bazzite), Handheld/HTPC (Bazzite-Deck), and Developer eXperience (Bazzite-DX)). It is based on Fedora Linux and features an atomic update system, ensuring the previous update is always available if something goes wrong.</p> <p>It is also designed for daily driving, with a focus on gaming, multi-media, and development.  In addition, since Bazzite ships the latest drivers, you can be sure that if your device can work on Linux, then it will work in Bazzite.  Bazzite has support for AMD, recent Nvidia and Intel GPUs. Bazzite also works well for Lenovo, Asus, Ayn, GPD, and OneXPlayer handheld devices.</p>"},{"location":"General/SteamOS_Comparison/#extra-enhancements-on-bazzite-compared-to-steamos","title":"Extra Enhancements on Bazzite Compared to SteamOS","text":"<ul> <li>Excellent dual-boot support with Windows.</li> <li>Works on most x86-based handhelds: Lenovo Legion Go/S, ASUS ROG Ally/X, OneXPlayer F1/G1/X1 variants, GPD Win 4/Mini/Max, Ayn Loki, MSI Claw 1<sup>st</sup> Gen AI7+/8+, Zotac Zone, Ayaneo Air/Geek/Next, Steam Deck LCD/OLED.</li> <li>Support for tuning desktop GPUs and fans.</li> <li>Fearless Updates<ul> <li>You always have access to the previous version through the bootloader.</li> <li>For handhelds, Bazzite will automatically rollback on the previous version after 3 failed boots.</li> <li>A backlog of the previous 90 days of updates is available, and you can easily roll back to any version with a simple command or through Handheld Daemon.</li> </ul> </li> <li>Ships the newest software available including the Linux kernel, graphics drivers, and Gamescope.</li> <li>Useful gaming-related software, such as Lutris, Umu-Launcher, ProtonUp-QT, Protontricks, and more.</li> <li>Access to the GNOME desktop environment as an alternative to KDE Plasma.</li> <li>Out of the box support for virtualization and GPU passthrough.</li> <li>Android applications can be installed with Waydroid.</li> <li>Sunshine is pre-installed, allowing you to easily stream your games.</li> <li><code>ujust</code> convenience scripts for setting up software and tweaks such as secure boot, and additional software.</li> <li>Uses the disk format BTRFS with deduplication and compression (SteamOS uses Ext4) and supports auto-mounting for both internal drives and SD cards.</li> </ul>"},{"location":"General/SteamOS_Comparison/#daily-driving","title":"Daily Driving","text":"<ul> <li>System packages are updated frequently.</li> <li>Wayland is used in desktop mode, ensuring correct scaling for high-DPI displays.</li> <li>Most desktop packages follow the Fedora lifecycle, with exceptions where there is a bug, where the package is selectively withheld or fixed earlier than Fedora.</li> </ul>"},{"location":"General/SteamOS_Comparison/#for-developers","title":"For Developers","text":"<ul> <li>Access to multiple package managers and repositories in containers using Distrobox.</li> <li>Homebrew is pre-installed for command-line packages.</li> <li>Layer Fedora packages to the system which survive between system updates.</li> <li>Check out Development for more information.</li> </ul>"},{"location":"General/SteamOS_Comparison/#security-improvements","title":"Security Improvements","text":"<p>Bazzite supports LUKS Disk Encryption, Secure Boot, and TPM unlock of the encrypted disk. Bazzite also has SELinux (Security Enhanced Linux) enabled and pre-configured by default.</p> <p>Secure Boot support is also useful for dual-booting with Windows, since it is required for certain anti-cheat software. Read more in the Secure Boot Guide.</p>"},{"location":"General/VPN/","title":"VPN Setup","text":""},{"location":"General/VPN/#using-functional-vpn-flatpaks","title":"Using functional VPN Flatpaks","text":"<p>VPN clients are usually not offered on the Bazaar app store as the Flatpak sandbox is too strict for most VPN clients to work as is which means they are not available in Bazaar to install. However examples of good VPN clients that are available in Bazaar:</p> <ul> <li>Mozilla VPN</li> <li>ProtonVPN</li> </ul>"},{"location":"General/VPN/#tailscale","title":"Tailscale","text":"<p>Tailscale is included by default to provide VPN services for both desktop and development use cases. Read this Tailscale guide for common usage before proceeding.</p> <ul> <li>Using Tailscale with Mullvad - Provides the best out of the box experience.<ul> <li>Using Tailscale with Docker - For development purposes.</li> <li><code>ujust toggle-tailscale</code> will remove the built in desktop integration if you prefer to use something else.</li> <li>Tailscale's YouTube channel has lots of great tips and tricks.</li> </ul> </li> <li>Good VPNs provide Wireguard configuration files that can be imported directly into NetworkManager, check your VPN providers documentation for more information.</li> <li>Only as a last resort layer the VPN with rpm-ostree.</li> </ul>"},{"location":"General/VPN/#import-vpn-configuration-files-through-desktop-environment","title":"Import VPN configuration files through Desktop Environment","text":"<p>This option may be good enough for you if you don't need special features provided by your VPN client, like kill-switches, split tunneling and other custom features not built-in to the VPN protocol. VPNs imported in this way can be toggled on and off at will.</p> KDE PlasmaGNOME <p>1. Open System Settings 2. Navigate to the Networking Section and go into the \"Wi-Fi &amp; Internet\" settings 3. Click the \"+\" button at the bottom</p> <p></p> <p>4. Select your downloaded configuration file</p> <p></p> <p>1. Open Settings 2. Navigate to the Network section 3. Click the \"+\" button on the VPN section</p> <p></p> <p>4. Choose \"Import From file...\"</p> <p></p> <p>5. Select your downloaded configuration file.</p>"},{"location":"General/community-links/","title":"Community Resources","text":"<p>Note</p> <p>There are links contained here that redirect to other sources that are not considered official documentation, but are considered good community-oriented resources, guides, and enhancements for Bazzite and the hardware that it is commonly installed on.</p> <p>Warning</p> <p>Some of these resources may be outdated, please follow them at your own risk.</p>"},{"location":"General/community-links/#hardware","title":"Hardware","text":"<ul> <li>Framework Linux Guides</li> <li>Framework Laptop Guides</li> <li>Lenovo Legion Go Tips and Tricks</li> <li>How to Update the BIOS on the Lenovo Legion Go from Bazzite (No Windows Required) [Potential Risk of Bricking Handheld]</li> <li>GPD Win Tips and Tricks</li> <li>Minisforum V3 Tips and Tricks</li> <li>HUION H1060P Drawing Tablet Workaround (Also works for other non-Wacom tablets that have issues with OpenTabletDriver)</li> <li>Beelink GTR6 Compatibility List</li> <li>Wake on Lan Via Ethernet Tutorial</li> <li>USB Wakeup on Bazzite</li> </ul>"},{"location":"General/community-links/#software-gaming","title":"Software / Gaming","text":"<ul> <li>OLD Bazzite Portal Application List</li> <li>Microsoft's Tutorial on Xbox Cloud Streaming for Game Pass Ultimate (and Fortnite)</li> <li>Browser Games Using Web Apps</li> <li>StreamingServiceLauncher</li> <li>Crunchyroll for Linux</li> <li>Running Valve's Hammer Level Editor Software for Map Making in the Source 1 Engine</li> <li>boxkit: Template to build your own OCI Distrobox container</li> <li>bazzite-arch: Gaming packages inside of a Distrobox container</li> <li>davincibox: Container for DaVinci Resolve installation and runtime dependencies</li> <li>DAWbox: An Ubuntu based OCI ready for music production, powered by Distrobox</li> <li>ZeroTier Setup</li> <li>Installing Arctis Manager</li> </ul>"},{"location":"General/community-links/#bootable-container-topics","title":"Bootable Container Topics","text":"<ul> <li>List of Bootable Container Images</li> <li>Bootcrew</li> <li>secureblue</li> <li>Blue95</li> <li>Wayblue</li> <li>Pocketblue</li> <li>HeliumOS</li> <li>List of Community Created Custom Images</li> <li>Installing Universal Blue's Base Images</li> <li>Self-Hosting Images</li> <li>BlueBuild Project</li> </ul>"},{"location":"General/community-links/#reference-documentation","title":"Reference Documentation","text":"<ul> <li>Fedora Kinoite Documentation</li> <li>Fedora Silverblue Documentation</li> <li>Aurora Documentation</li> <li>Bluefin Documentation</li> <li>Bazzite Newsletter Archive</li> <li>DeepWiki</li> </ul>"},{"location":"General/community-links/#contribute","title":"Contribute","text":"<p>Edit this documentation to add other useful external resources!</p>"},{"location":"General/issues_and_resolutions/","title":"Common Issues &amp; Resolution","text":""},{"location":"General/issues_and_resolutions/#steam-big-picture-mode-is-slow","title":"Steam Big Picture Mode is slow","text":"<p>Issue: When you select Steam Menu &gt;&gt; View &gt;&gt; Big Picture the user interface may run sluggish. However, the games that run through the interface are working smoothly.</p> <p>Resolution: Close Steam completely and start Steam using the Steam Big Picture Mode menu shortcut. Also make sure that Steam Settings &gt;&gt; Interface &gt;&gt; Enable GPU accelerated rendering in web views (requires restart) is enabled in the Steam settings.</p> <p>Note: This fix also fixes the performance issues in Steam Gamming Mode on Nvidia GPUs, however, this comes with a drawback that the Steam menu and side menu sometimes do not render properly.</p>"},{"location":"General/issues_and_resolutions/#audio-is-soft-on-asus-rog-ally-hardware","title":"Audio is soft on ASUS ROG Ally hardware","text":"<p>Issue: The sound is quiet even if at maximum volume.</p> <p>Resolution: There are two audio devices that appear on the Rog Ally: - Family 17h/19h/1ah HD Audio Controller - ROG Ally</p> <p>Both affect each other's audio volume so they must be at the same volume level.</p>"},{"location":"General/issues_and_resolutions/#gamepads-and-handheld-joysticks-dont-work-in-desktop-mode","title":"Gamepads and handheld joysticks don't work in Desktop Mode","text":"<p>Issue: Gamepads and handheld device joysticks don't work in desktop mode, so you have to use the touchscreen or connect an external mouse.</p> <p>Open up Steam Settings &gt;&gt; Controller &gt;&gt; Non-Game Controller Layouts &gt;&gt; Desktop Layout. Click on Edit Then Enable Steam Input and configure how the controller needs to as a keyboard and mouse in Desktop Mode.</p> <p>You'll often need to reduce the Right Joystick Sensitivity to somewhere between 50-80%. Otherwise, the mouse cursor will be too fast and will not be reliable.</p>"},{"location":"General/issues_and_resolutions/#setting-bazzites-desktop-editions-to-automatically-login","title":"Setting Bazzite's Desktop Editions to automatically login","text":"<p>Issue: How do you configure automatic login in Bazzite?</p> KDE Plasma Resolution <p>Open System Settings &gt;&gt; Colors and Themes &gt;&gt; Login Screen (SDDM) then on the right side of the screen there will be a button labelled Behaviour, click on it.</p> <p>Now tick \"Automatically log in\", select your user and for the session, select \"Plasma (Wayland)\" and don't forget to to click on the \"Apply\" button.</p> GNOME Resolution <p>Open the Settings application &gt;&gt; Users. Click the Unlock button in the top right corner. Then switch on Automatic Login.</p>"},{"location":"General/issues_and_resolutions/#htpc-legacy-hardware-setup","title":"HTPC legacy hardware setup","text":"<p>Issue: How do you setup a similar version to Bazzite-Deck using GPU hardware that is considered \"legacy\" and unsupported for Steam Gaming Mode?</p> <p>Resolution: Enable auto-login and set Steam to automatically launch in Steam's Big Picture Mode for a decent couch gaming experience if you have legacy hardware.</p> <p>There is a video guide that you can follow for Bazzite's GNOME Desktop image using a Nvidia GPU (before Nvidia hardware could run Steam Gaming Mode, but same idea):</p> <p></p> <p>If you are using Bazzite's KDE Plasma image, then you can skip the \"Making Gnome look more familiar to Windows users\" section, and use the steps above to get auto login working in Bazzite KDE. Then finally set Steam Big Picture Mode to auto-start in Settings &gt;&gt; Autostart.</p>"},{"location":"General/issues_and_resolutions/#no-wi-fi-or-wired-connection-in-bazzite-when-dual-booting-with-windows","title":"No Wi-Fi or wired connection in Bazzite when dual-booting with Windows","text":"<p>Issue: You are dual-booting Windows with Bazzite and your Wi-Fi/wired connection works in Windows but fails in Bazzite sometimes.</p> <p>Resolution: Fast Startup is a feature of Windows that puts your computer into a hybrid state between shutdown and hibernation to speed up the time it takes for Windows to start up. However, this setting can lock up hardware devices such as your Wi-Fi, ethernet and perhaps other hardware.  One solution is to select the Restart option instead of the Shutdown option, which will perform a full power cycle. However, a better solution is to simply disable Fast Startup.</p> <p>You can do this by:</p> <ul> <li>Open Control Panel</li> <li>Click on Hardware and Sound</li> <li>Click on Change what the power buttons do which is under Power Options</li> <li>Click on Change settings that are currently unavailable</li> <li>Untick Turn on fast startup (recommended)</li> <li>(Optional) Untick Hibernate too if you don't use it as it can cause the same issues as Fast Startup</li> <li>Click on Save changes</li> </ul> <p></p> <p>Now if you now select the Shutdown option, Windows will shut down completely and not interfere with Bazzite.</p>"},{"location":"General/issues_and_resolutions/#wi-fi-is-slow-wi-fi-lag-spikes","title":"Wi-Fi is slow / Wi-Fi lag spikes","text":"<p>Issue: Your Wi-Fi performance is much slower than expected or has lag spikes, which interferes with voice chat and online games. The problem is not present in Windows.</p> <p>Resolution: The Wi-Fi power saving feature in Linux seems to work poorly on some Wi-Fi devices under Linux.  Open the terminal and run <code>ip link show</code> this will list all your network devices and the output should look something like this:</p> <pre><code>1: lo: &lt;LOOPBACK,UP,LOWER_UP&gt; mtu 65536 qdisc noqueue state UNKNOWN mode DEFAULT group default qlen 1000\n    link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00\n2: wlp6s0: &lt;BROADCAST,MULTICAST,UP,LOWER_UP&gt; mtu 1500 qdisc noqueue state UP mode DORMANT group default qlen 1000\n    link/ether 00:00:00:00:00:00 brd ff:ff:ff:ff:ff:ff permaddr 00:00:00:00:00:00\n</code></pre> <p>The device that we are interested in is the Wi-Fi device. In this example (my ROG Ally), the Wi-Fi network is called <code>wlp6s0</code>. Another common name for the Wi-Fi network is <code>wlan0</code>.</p> <p>Next run <code>iw wlp6s0 get power_save</code> (change <code>wlp6s0</code> if your device name is different) to confirm if power saving is on: <pre><code>Power save: on\n</code></pre></p> <p>There are different steps to resolve this depending on if you've disabled iwd. If you have updated or installed Bazzite after 1<sup>st</sup> Jan 2026, iwd will be set as the default WiFi backend.</p> <p>For performance reasons, and to fix certain issues in relation to streaming, <code>iwd</code> replaced <code>wpa_supplicant</code> as the default WiFi backend for Bazzite since 2026. To switch back, run <code>ujust toggle-iwd</code>. Note that switching will remove all network configurations.</p> iwd (iwd is ON)wpa_supplicant (iwd is OFF) <p>We are going to configure iwd to not use the power save feature for all Wi-Fi devices. Open a terminal and run</p> <pre><code>printf \"[DriverQuirks]\\nPowerSaveDisable = *\" | sudo tee /etc/iwd/main.conf\nsystemctl restart iwd\n</code></pre> <p>Next, run <code>iw wlp6s0 get power_save</code> to confirm that power save is off: <pre><code>Power save: off\n</code></pre></p> <p>Note that this fix may negatively affect the battery life of your laptop or handheld. If you do wish to reverse this change, just delete the config file: <pre><code>sudo rm /etc/iwd/main.conf\nsystemctl restart iwd\n</code></pre></p> <p>We are going to configure NetworkManager to not use the power save feature for all Wi-Fi devices. Open a terminal and run</p> <pre><code>printf \"[connection]\\nwifi.powersave = 2\" | sudo tee /etc/NetworkManager/conf.d/wifi-powersave-off.conf\nsystemctl restart NetworkManager\n</code></pre> <p>Next, run <code>iw wlp6s0 get power_save</code> to confirm that power save is off: <pre><code>Power save: off\n</code></pre></p> <p>Note that this fix may negatively affect the battery life of your laptop or handheld. If you do wish to reverse this change, just delete the config file: <pre><code>sudo rm /etc/NetworkManager/conf.d/wifi-powersave-off.conf\nsystemctl restart NetworkManager\n</code></pre></p>"},{"location":"General/issues_and_resolutions/#error-on-connecting-to-wi-fi-failed-to-add-new-connection-8021x-connections-must-have-iwd-provisioning-files","title":"Error on connecting to Wi-Fi: \"Failed to add new connection: 802.1x connections must have IWD provisioning files\"","text":"<p>For performance reasons, and to fix certain issues in relation to streaming, <code>iwd</code> replaced <code>wpa_supplicant</code> as the default WiFi backend for Bazzite since 2026. To switch back, run <code>ujust toggle-iwd</code>. Note that switching will remove all network configurations.</p> <p>NetworkManager cannot automatically generate 802.1x connections when using the <code>iwd</code> backend.</p> <p>If you prefer to keep using the <code>iwd</code> backend and just want to connect to <code>eduroam</code>, follow these steps:</p> <pre><code>sudo nano /var/lib/iwd/eduroam.8021x\n</code></pre> <p>Then add the following:</p> <pre><code>[Security]\nEAP-Method=PEAP\nEAP-Identity=anonymous@&lt;university.domain&gt;\nEAP-PEAP-Phase2-Method=MSCHAPV2\nEAP-PEAP-Phase2-Identity=&lt;username@university.domain&gt;\nEAP-PEAP-Phase2-Password=&lt;password&gt;\n\n[Settings]\nAutoConnect=true\n</code></pre> <p>Make sure to replace <code>&lt;university.domain&gt;</code>, <code>&lt;username@university.domain&gt;</code> and <code>&lt;password&gt;</code> with proper login information. Afterwards, press <code>Ctrl+X</code> and <code>Y</code> to Save &amp; Exit.</p> <p>Now try to connect again. If you still can't connect, execute:</p> <pre><code>nmcli connection modify eduroam 802-1x.phase1-auth-flags 32\n</code></pre> <p>And try to connect again.</p> <p>If you still encounter Wi-Fi related issues, try reverting to the <code>wpa_supplicant</code> backend or reach out to support on https://discord.bazzite.gg.</p>"},{"location":"General/issues_and_resolutions/#error-on-connecting-to-wi-fi-ip-configuration-was-unavailable-when-connecting-to-8021x-wireless-networks","title":"Error on connecting to Wi-Fi: \"IP configuration was unavailable\" when connecting to 802.1x wireless networks","text":"<p>For performance reasons, and to fix certain issues in relation to streaming, <code>iwd</code> replaced <code>wpa_supplicant</code> as the default WiFi backend for Bazzite since 2026. To switch back, run <code>ujust toggle-iwd</code>. Note that switching will remove all network configurations.</p> <p>Check the system logs with <code>ujust logs-this-boot | grep NetworkManager</code>, you should be able to see that </p> <pre><code>NetworkManager[1563]: &lt;info&gt;  [1770094603.8488] device (wlan0): state change: failed -&gt; disconnected (reason 'none', managed-type: 'full')\nNetworkManager[1563]: &lt;info&gt;  [1770094603.8568] dhcp4 (wlan0): canceled DHCP transaction\nNetworkManager[1563]: &lt;info&gt;  [1770094603.8569] dhcp4 (wlan0): activation: beginning transaction (timeout in 45 seconds)\nNetworkManager[1563]: &lt;info&gt;  [1770094603.8569] dhcp4 (wlan0): state changed no lease\n</code></pre> <p>When using the <code>iwd</code> backend, NetworkManager may be unable to obtain a DHCP lease on an Enterprise network if you have connected to it previously on a different backend or a different OS. </p> <p>If you prefer to keep using the <code>iwd</code> backend, follow these steps:</p> <pre><code>sudo mkdir -p /etc/iwd/\nsudo nano /etc/iwd/main.conf\n</code></pre> <p>Then add the following:</p> <pre><code>[General]\nAddressRandomization=network\n</code></pre> <p>Afterwards, press <code>Ctrl+X</code> and <code>Y</code> to Save &amp; Exit, then reload <code>iwd</code> by running:</p> <pre><code>systemctl daemon-reload\nsystemctl restart iwd\n</code></pre> <p>You should be able to connect to the enterprise network. If you still encounter Wi-Fi related issues, try reverting to the <code>wpa_supplicant</code> backend or reach out to support on https://discord.bazzite.gg.</p>"},{"location":"General/issues_and_resolutions/#nvidia-optimus-gpu-not-detected-on-laptops","title":"Nvidia Optimus GPU not detected on laptops","text":"<p>Issue: If you are running Bazzite on a laptop with an Nvidia Optimus GPU, you might notice that games are running poorly and seem to be running on the integrated GPU.</p> <p>Resolution: You need to enable supergfxctl which will automatically switch to the discrete Nvidia GPU when launching your games. Open a terminal and run:</p> <pre><code>ujust enable-supergfxctl\n</code></pre>"},{"location":"General/issues_and_resolutions/#waking-from-sleep-doesnt-work-with-a-gigabyte-b550-motherboard","title":"Waking from sleep doesn't work with a Gigabyte b550 motherboard","text":"<p>Issue: Once a Gigabyte b550 motherboard suspends, it does not properly resume, and the display remains black until a reboot.</p> <p>Resolution: This can be fixed by disabling GPP0 and GPP8 wakeup. A hidden ujust command is provided to toggle this fix: <pre><code>ujust _toggle-gigabyte-wake-fix\n</code></pre></p>"},{"location":"General/issues_and_resolutions/#xbox-controller-over-bluetooth-is-stuck-on-a-connecting-loop-and-the-xbox-button-keeps-flashing","title":"Xbox controller over Bluetooth is stuck on a connecting loop and the Xbox button keeps flashing","text":"<p>Issue: Your controller is not on the latest firmware.</p> <p>Resolution: Easiest solution here is to connect the controller to a Windows machine. Download the Xbox Accessories app and update the controller to the latest firmware. After that, the controller should connect seamlessly. A more advanced user could spin a Windows VM and pass through the controller to do the firmware update there.</p>"},{"location":"General/reporting_bugs/","title":"Reporting Bugs","text":""},{"location":"General/reporting_bugs/#submit-bug-reports-in-the-appropriate-place","title":"Submit bug reports in the appropriate place","text":"<p>Report bugs experienced with Bazzite in our issue tracker! We discourage reporting bugs in the Discourse forums since reports can get lost or may not be viewed by Bazzite contributors as often as the issue tracker.</p>"},{"location":"General/reporting_bugs/#bazzite-issue-template-walkthrough","title":"Bazzite Issue Template Walkthrough","text":""},{"location":"General/reporting_bugs/#update-bazzite-before-reporting","title":"Update Bazzite before reporting","text":"<p>Sometimes bugs are fixed during upgrades, so try updating and rebooting your device before submitting a report to see if the issue still persists between updates.</p> <p>Read how to update Bazzite for your device: Updating guide</p>"},{"location":"General/reporting_bugs/#make-sure-to-attach-system-logs","title":"Make sure to attach system logs","text":"<p>Open a host terminal and enter:</p> <pre><code>ujust device-info\n</code></pre> <p>Attach the link that it outputs for system logs.</p>"},{"location":"General/reporting_bugs/#experience-system-crashes","title":"Experience system crashes?","text":"<p><pre><code>ujust logs-last-boot\n</code></pre> Copy the output inside of the bug report. </p>"},{"location":"General/terms/","title":"Dictonary &amp; Terminology","text":""},{"location":"General/terms/#general","title":"General","text":"<ul> <li>[Desktop] Linux: A family of operating systems that share many of the same core software including the Linux kernel, systemd and the GNU core utilities.</li> <li>Desktop Environment: The graphical user interface (UI) and user experience (UX) for the Desktop Mode / Desktop images for Bazzite. Also known as a DE.</li> <li>Fedora Linux: A leading edge Linux operating system that has a new major release every 6 months.</li> <li>Fedora Atomic Desktop: An experimental version of Fedora Linux created to be as reliable and reproducible. Two of the most popular variants are known as Fedora Silverblue and Fedora Kinoite for the specific desktop environments that they use (GNOME and KDE Plasma respectively).</li> <li>\"Immutable\": A term to describe Linux operating systems that do not follow the traditional filesystem layout where every single file can be removed by the user with root privileges.  It is more nuanced than this in the case of Bazzite, and is often wrongly considered \"immutable\" from the point of view of the extended Linux community.  The Bazzite team would not describe Bazzite as an \"immutable\" operating system.</li> <li>Open Gaming Collective (OGC): A working group for organizations and individuals interested in providing a collaborative framework for upstream changes to the various gaming components that will benefit all Linux gaming focused projects.</li> </ul>"},{"location":"General/terms/#bazzite-deck-images","title":"Bazzite-Deck Images","text":"<ul> <li>Steam Deck: Valve's gaming handheld PC that utilizes their own operating system which runs their own Linux operating system based around the Steam client.</li> <li>SteamOS: Valve's Linux operating system based on Arch Linux that the Steam Deck runs.</li> <li>Gamescope: Micro-compositor developed for SteamOS.  Usage includes scaling, filtering, framerate limiting, and HDR support.</li> <li>Steam Gaming Mode: A session that runs Steam's Big Picture Mode user interface inside of Gamescope.  Also known as Game Mode.</li> </ul>"},{"location":"General/terms/#software","title":"Software","text":"<ul> <li>Proton: Gaming-focused compatibility layer maintained by Valve to run Windows games using WINE, DXVK, VKD3D, and other components.</li> <li>Vulkan: Cross-platform, open standard graphics API derived from AMD's Mantle as an alternative to DirectX, which is Windows exclusive.</li> <li>OpenGL: Legacy graphics API when Vulkan is not available.</li> <li>Flatpak: Universal applications for Linux.  The default remote is from Flathub.</li> <li>Containers - Isolated environments for software.</li> </ul>"},{"location":"General/terms/#underlying-technology","title":"Underlying Technology","text":"<ul> <li>OSTree/libostree: Upgrade system that Bazzite utilizes that allows for rolling back previous system updates or rebasing to different images entirely.</li> <li>Handheld Daemon (HHD): Handheld hardware-enablement software that provides controller functionality, power utilization, RGB, and more.</li> <li>Universal Blue: A FOSS collective that specializes in custom Fedora images.</li> <li>Bootable Container Image: Software and services are packaged inside of a container that run on top of an existing operating system (like Fedora) as as a means of delivering a specialized operating system.  Also known as a custom image.</li> <li>Cloud-Native: Building and deploying software in an automated fashion. Provides features such as over-the-air updates, multiple images that receive the same upgrades upstream, etc.  For the case of Bazzite, every single upgrade is done in Github.</li> </ul>"},{"location":"General/uninstalling-bazzite/","title":"Uninstalling Bazzite and Returning to Windows","text":""},{"location":"General/uninstalling-bazzite/#removing-bazzite-in-a-windows-dual-boot-scenario","title":"Removing Bazzite in a Windows Dual-Boot Scenario","text":"<p>Watch the video guide below:</p> <p></p>"},{"location":"General/Installation_Guide/","title":"Installing Bazzite","text":"<ul> <li>Installation Guide</li> <li>Post-Installation Setup</li> <li>Installation Troubleshooting</li> <li>Legacy ISO Installer Guide </li> <li>Alternative Installation Guide</li> </ul>"},{"location":"General/Installation_Guide/Installing_Bazzite_Framework_Laptop_13/","title":"Installing Bazzite Framework Laptop 13","text":""},{"location":"General/Installation_Guide/Installing_Bazzite_for_Framework_Laptop_16/","title":"Installing Bazzite for Framework Laptop 16","text":""},{"location":"General/Installation_Guide/alternate-install-guide/","title":"Alternative Installation Guide","text":"<p>Warning</p> <p>This method may have scaling issues with the installer depending on the hardware especially if it is handheld PC hardware.</p>"},{"location":"General/Installation_Guide/alternate-install-guide/#rebasing-from-a-fedora-atomic-desktop-image","title":"Rebasing from a Fedora Atomic Desktop Image","text":"<p>If you experience issues with installing our ISO or the bootable drive you have is too small for Bazzite, then download the Fedora Kinoite (KDE Plasma) or Fedora Silverblue (GNOME) depending on which desktop environment you prefer.</p> <ol> <li> <p>The installation setup is similar to Bazzite and includes the same installer with the same instructions, but do not set a root account if its an option in the installer.</p> </li> <li> <p>Once installed, you will not be on Bazzite until you enter the command found on our website that appears under \"Existing Fedora Atomic Desktop Users\" section when the download is ready or by referencing the full image list in the FAQ.</p> </li> <li> <p>Open the terminal and enter this command, and keep in mind this process has no progress indicator and will take a long time.</p> </li> <li> <p>Reboot when the rebase has finished, and Bazzite should be installed after rebooting and your username as well as the user password will carry over from the upstream Fedora Atomic Desktop to Bazzite.</p> </li> <li> <p>You will also be missing the default Flatpak applications unless you install them with the <code>ujust</code> command below.</p> </li> </ol>"},{"location":"General/Installation_Guide/alternate-install-guide/#secure-boot-instructions-when-rebasing-from-upstream-fedora-atomic-desktop-images","title":"Secure Boot Instructions When Rebasing From Upstream Fedora Atomic Desktop images","text":"<p>Rebasing from Fedora Silverblue, Fedora Kinoite, etc. to Bazzite.</p> <p>If you're rebasing from a Fedora Atomic Desktop image and use Secure Boot, then follow the instructions found in Bazzite's README.</p>"},{"location":"General/Installation_Guide/alternate-install-guide/#install-pre-installed-flatpak-applications","title":"Install Pre-Installed Flatpak Applications","text":"<p>Open the terminal and enter this command:</p> <pre><code>ujust _install-system-flatpaks\n</code></pre> <p>Choose the \"Flathub\" remote.  If it asks for \"System\" or \"User\" then choose \"System\" since that is the default remote for Bazzite.</p> <p>This command installs:</p> <ul> <li>Flatpak applications for KDE Plasma images</li> <li>Flatpak applications for GNOME images</li> </ul>"},{"location":"General/Installation_Guide/alternate-install-guide/#remove-fedora-flatpak-remote","title":"Remove Fedora Flatpak Remote","text":"<p>Please remove the Fedora Flatpak remote using the Warehouse application.  This will not remove userdata.</p>"},{"location":"General/Installation_Guide/alternate-install-guide/#rebasing-to-a-signed-image","title":"Rebasing to a signed image","text":"<p>Once everything is setup properly, then you should rebase from the unsigned image to the signed image for security reasons, so enter this command in the host terminal:</p> <p><pre><code>ujust verify-image\n</code></pre> After the command is completed, reboot your device.</p>"},{"location":"General/Installation_Guide/alternate-install-guide/#video-tutorial","title":"Video Tutorial","text":""},{"location":"General/Installation_Guide/install-guide/","title":"Bazzite Installation Guide","text":""},{"location":"General/Installation_Guide/install-guide/#video-walkthrough","title":"Video Walkthrough","text":""},{"location":"General/Installation_Guide/install-guide/#system-requirements","title":"System Requirements","text":"<ul> <li>Read the Hardware Compatibility Guide for Bazzite's system requirements.</li> <li>Secure Boot and Trusted Platform Module (TPM) are supported on most hardware, but you must enroll our key during or after installation.</li> <li>Dual-booting with Windows is also supported.</li> </ul>"},{"location":"General/Installation_Guide/install-guide/#installer-requirements","title":"Installer Requirements","text":"<ul> <li>A way to download the Bazzite ISO<ul> <li>A download manager (like Motrix) if the direct download for the Bazzite ISO fails or is downloading too slow.</li> </ul> </li> <li>A 16GB+ bootable medium like a Flash Drive<ul> <li>Booting from a SD or microSD card may work, but not all firmware support this.</li> </ul> </li> <li>One of the following programs to flash/boot the ISO:<ul> <li>Fedora Media Writer (recommended) (Windows/macOS, Linux)</li> <li>Rufus (Windows) (DD Image mode required)</li> <li>Ventoy (Windows, Linux) (note: Ventoy needs extra steps for Secure Boot Support to work)</li> </ul> </li> <li>A physical wired keyboard is recommended and required for devices without a touchscreen.<ul> <li>An on-screen keyboard exists for scenarios where you do not have a physical USB keyboard.<ul> <li>A touchscreen display or a mouse is required to navigate the installer properly.</li> </ul> </li> </ul> </li> </ul>"},{"location":"General/Installation_Guide/install-guide/#desktop-environments","title":"Desktop Environments","text":"<p>All of the images come with the choice of KDE Plasma or GNOME for their desktop environment.</p> <p>Steam Gaming Mode is an option as an additional session to run in addition to KDE Plasma or GNOME.</p> <p>More information can be found on Bazzite's FAQ about the differences between the image variants.</p> KDE PlasmaGNOMESteam Gaming Mode"},{"location":"General/Installation_Guide/install-guide/#kde-plasma-default","title":"KDE Plasma (Default)","text":"<ul> <li>KDE Plasma's default interface has a traditional and familiar layout</li> <li>Highly customizable with tons of settings</li> <li>Qt framework</li> <li>Popular Linux distributions like SteamOS use KDE Plasma</li> </ul>"},{"location":"General/Installation_Guide/install-guide/#gnome-gnome-images","title":"GNOME (<code>-gnome</code> images)","text":"<ul> <li>GNOME's default interface has an elegant and touch-friendly layout</li> <li>Simple and concise</li> <li>GTK framework</li> <li>Popular Linux distributions like Ubuntu use GNOME</li> </ul>"},{"location":"General/Installation_Guide/install-guide/#steam-gaming-mode-deck-images","title":"Steam Gaming Mode (<code>-deck</code> images)","text":"<p>Note</p> <p>Your device will automatically boot into the Steam Gaming Mode session at startup, and Desktop Mode can be accessed from the \"power menu\" in Steam Gaming Mode.</p> <ul> <li>Requires a Steam account</li> <li>Included in the Bazzite-Deck images</li> <li>Interface is designed for handheld and couch gaming</li> <li>Controller friendly</li> <li>Choice of KDE Plasma or GNOME as the Desktop Mode session</li> <li>Extra functionality with Decky plugins (See all plugins)</li> </ul>"},{"location":"General/Installation_Guide/install-guide/#backup-device","title":"Backup Device","text":"<p>Make sure to backup your personal data from the drive you plan to install Bazzite on to a safe place before proceeding with the installation.</p>"},{"location":"General/Installation_Guide/install-guide/#download-bazzite","title":"Download Bazzite","text":"<p>Download the Bazzite ISO of your choice. Choose the hardware you plan to install Bazzite on, the vendor of your primary GPU, the desktop environment of your choice, and if you want Steam Gaming Mode which is the Bazzite-Deck variant intended for HTPC setups and handheld hardware.</p>"},{"location":"General/Installation_Guide/install-guide/#calculating-iso-sha256-checksum-hash","title":"Calculating ISO SHA256 Checksum Hash","text":"<p>Video Tutorial:</p> <p></p>"},{"location":"General/Installation_Guide/install-guide/#flash-iso","title":"Flash ISO","text":"<p>Flash Bazzite to your bootable device using Fedora Media Writer and eject the ISO afterwards.</p>"},{"location":"General/Installation_Guide/install-guide/#booting-the-installer","title":"Booting The Installer","text":"<ul> <li>Connect your bootable medium to your device and boot into it.</li> <li>After connecting the device, boot into the Bazzite installer.</li> <li>This depends on your motherboard hardware, but most of the time it could be a function key like F9 or similar.<ul> <li>Sometimes you need to consult the manual, look up your device online, or read any hotkeys that appear when you boot your PC.<ul> <li>Alternatively change the BIOS settings to boot with your bootable device first before your current storage, but this is not recommended to keep enabled after installing Bazzite.</li> </ul> </li> </ul> </li> </ul>"},{"location":"General/Installation_Guide/install-guide/#handheld-devices","title":"Handheld Devices","text":"<p>Hold the 'Volume Down' (-) button and click the Power Button, and when you hear the chime, let go of both buttons, and you'll be booted into the Boot Manager. When you get to the boot menu, select your bootable device to boot into the Bazzite installer.</p>"},{"location":"General/Installation_Guide/install-guide/#live-environment","title":"Live Environment","text":"<p>Bazzite's live installer session lets you view the desktop applications pre-installed and get familiar with the UI/UX of it.  </p> <p>Please do not attempt to game on the live session since performance will not be accurate to when it is properly installed onto your drive. Additionally, it is worth noting that the install environment does not include all of Bazzite's hardware support, (for example for the Steam Deck Audio), as it is running a different kernel than regular Bazzite.</p>"},{"location":"General/Installation_Guide/install-guide/#network-setup-in-live-environment","title":"Network Setup in Live Environment","text":"<p>Please note that an internet connection is not required to install Bazzite, but is useful if you're testing Bazzite before testing in the live environment.  Open the Bazzite installer when ready to proceed with installation.</p>"},{"location":"General/Installation_Guide/install-guide/#select-your-language-region-and-keyboard-layout","title":"Select Your Language, Region, and Keyboard Layout","text":"<p>The first steps to installing Bazzite include selecting the system language, region for your time zone, and the layout of your keyboard for the correct input mapping.</p>"},{"location":"General/Installation_Guide/install-guide/#partitioning-setup","title":"Partitioning Setup","text":"<p>Warning</p> <p>Make sure to only select the appropriate drives to avoid losing data on others, and it is best practice to safely remove any external drives before proceeding.</p> <p>Select the drive that you plan to install Bazzite on. Please note that this will wipe all of the data on the drive selected.</p>"},{"location":"General/Installation_Guide/install-guide/#dual-booting-windows","title":"Dual Booting Windows","text":"<p>Note</p> <p>Skip this section if you plan to install Bazzite without dual-booting Windows.</p> <p>Warning</p> <p>The \"format as efi\" button when dual-booting says it will format the Windows EFI, but what it actually does is add itself to the EFI. This is an upstream bug with the installer.</p> <p>If you are dual-booting with Windows then use automatic partitioning as it is the only option available in the live ISO, but it should work for most people's dual-booting usecases.  If you require manual partitioning, then download the legacy ISO and follow the legacy ISO installation guide. For dual booting Windows on separate drives, use your motherboard's UEFI boot menu as the GRUB bootloader may not recognize each boot entry correctly.</p>"},{"location":"General/Installation_Guide/install-guide/#video-walkthrough_1","title":"Video Walkthrough","text":""},{"location":"General/Installation_Guide/install-guide/#written-walkthrough","title":"Written Walkthrough","text":"<ol> <li>Installing Bazzite with a shared drive.</li> <li>Installing Bazzite on a separate drive.</li> </ol> Shared Drive (Automatic Partitioning)Separate Drive <ol> <li>(In Windows) Disable Bitlocker encryption and fastboot, and reboot.</li> <li>(In Windows) Resize the Windows partition with the Disk Management app to have enough space for Bazzite. Usually should look something like this: Source: diskpart.com</li> <li>Run the Bazzite installer with the automatic partitioning option.</li> <li>Reboot into Bazzite and run <code>ujust regenerate-grub</code> in the terminal to add Windows to the GRUB.</li> </ol> <p>When a dedicated drive is feasible, this method is recommended.</p> <p>Install Bazzite on a separate internal or external drive.</p> <ol> <li>Install the other operating system on a drive (like Windows).</li> <li>Install Bazzite on a second drive.</li> <li>Set Bazzite as the default in your boot order (optional).</li> </ol> <p>If you install Windows second, you should disconnect the Bazzite drive to prevent using the Windows installer of using its EFI partition.</p> <p>You can also install Windows to an external drive with Windows-to-Go using Rufus to dual boot if you do not have an internal drive available.</p>"},{"location":"General/Installation_Guide/install-guide/#dual-booting-other-linux-operating-systems","title":"Dual-booting other Linux operating systems","text":"<p>Note</p> <p>Dual booting with other Linux distributions, especially non-atomic Fedora, is not officially supported. It is recommended to use your motherboard's UEFI boot menu or to forgo dual booting entirely to avoid unexpected issues. If something does go wrong, restore Bazzite's bootloader using the Bootloader Restoring Tool in the Live ISO.</p> <p>For Fedora Atomic Desktop images on the same drive: to dual boot another Fedora Atomic Desktop image (like Bluefin) installed alongside Bazzite, you must make an additional EFI partition and switch between them through your motherboard's UEFI boot menu.</p>"},{"location":"General/Installation_Guide/install-guide/#disk-encryption","title":"Disk Encryption","text":"<p>Warning</p> <p>It will not be possible to decrypt your drive and the data will be lost if you forget your encryption password!</p> <p>Disk encryption is optional but is available via LUKS. You will need a physical USB keyboard to decrypt the drive! Skip this step if you do not require disk encryption on this device. This isn't a necessary step for the most common scenarios unless you fear a bad actor will have access to your physical drive that Bazzite is installed on.</p>"},{"location":"General/Installation_Guide/install-guide/#user-account-setup","title":"User Account Setup","text":"<p>Warning</p> <p>It is not recommended to enable a root account.</p> <p>Create a username and a password to login to your Bazzite account.  This password will also be used for any administrative privileges.  Make sure it is a password that you can remember.</p>"},{"location":"General/Installation_Guide/install-guide/#installing-bazzite","title":"Installing Bazzite","text":"<p>Review the changes that you are about to make in the installer.  Please read carefully before proceeding with the installation. Please wait for Bazzite to install.  This may take a while.</p>"},{"location":"General/Installation_Guide/install-guide/#reboot","title":"Reboot","text":"<p>Reboot your device. You can now eject the flashable medium you used to install Bazzite out of your device once your device begins to boot up again.</p>"},{"location":"General/Installation_Guide/install-guide/#secure-boot","title":"Secure Boot","text":"<p>Note</p> <p>Skip this section if Secure Boot is not enabled or unsupported with your hardware.</p> <p>Important</p> <p>The enrollment prompt uses an English QWERTY keyboard layout, indiscriminately of your actual hardware keyboard. Other layouts can therefore interfere with the characters of the password (i.e. <code>A</code> and <code>Q</code> are swapped on AZERTY layouts).</p> <p>Bazzite supports Secure Boot however Universal Blue's key must be enrolled to use it otherwise keeping Secure Boot on in your BIOS will result in Bazzite not booting.</p>"},{"location":"General/Installation_Guide/install-guide/#important-secure-boot-notes","title":"Important Secure Boot Notes:","text":"<ul> <li>Entering the password will register invisible characters for security purposes, so you will not be able to see what you are typing!</li> <li>Updating your BIOS may re-enable Secure Boot and you may have to follow \"Method B\" after updating it to resolve the black screen on boot complaining about loading the kernel first.</li> <li>The Steam Deck does not come with secure boot enabled and does not ship with any keys enrolled by default, do not enable Secure Boot on your Steam Deck unless you absolutely know what you're doing.</li> </ul>"},{"location":"General/Installation_Guide/install-guide/#error-message-if-key-is-not-enrolled-properly","title":"Error Message (if key is not enrolled properly):","text":"<pre><code>error: ../../grub-core/kern/efi/sb.c:182:bad shim signature.\nerror: ../../grub-core/loader/1389/efi/linux.c:256:you need to load the kernel first.\n\nPress any key to continue...\n</code></pre> <p>Follow Method B below to resolve this and move past the error message if you encounter it.</p>"},{"location":"General/Installation_Guide/install-guide/#method-a-during-installation-method","title":"Method A - During Installation Method","text":"<p>Note</p> <p>This screen will also appear on the next boot if you enable Secure Boot if it was disabled during installation.</p> <p>A blue screen will appear giving the option to enroll the signed keys after leaving the Bazzite installer.</p> <p><code>Enroll MOK</code> if you have secure boot enabled. If prompted to enter a password, then enter:</p> <pre><code>universalblue\n</code></pre> <p>Otherwise <code>Continue boot</code> if you have Secure Boot disabled or if it is not supported with your hardware.</p>"},{"location":"General/Installation_Guide/install-guide/#method-b-after-installation-method","title":"Method B - After Installation Method","text":"<p>Disable Secure Boot in the BIOS before proceeding, and then re-enable it after enrolling the key.</p> <p>If you have already installed Bazzite then enter this command in a host terminal:</p> <pre><code>ujust enroll-secure-boot-key\n</code></pre> <p>If prompted to enroll the required key, then enter the password in the host terminal:</p> <pre><code>universalblue\n</code></pre> <p>You can now turn Secure Boot back on in the BIOS. Use the following command to boot straight into your system's BIOS (if supported):</p> <pre><code>ujust bios\n</code></pre>"},{"location":"General/Installation_Guide/install-guide/#complete-mok-enrollment-at-boot","title":"Complete MOK enrollment at boot","text":"<p>On the next boot, you will see the blue MokManager screen:</p> <ol> <li>Choose Enroll MOK.</li> <li>When prompted for a password, enter: <pre><code>universalblue\n</code></pre></li> </ol> <p>After the reboot, the key is enrolled and Secure Boot can remain enabled. Your system should now boot normally under Secure Boot.</p>"},{"location":"General/Installation_Guide/install-guide/#troubleshooting-installation","title":"Troubleshooting Installation:","text":"<p>Read the Troubleshooting Guide or the Alternative Installation Guide for installation workarounds.</p>"},{"location":"General/Installation_Guide/install-guide/#post-installation","title":"Post-Installation","text":"<p>Bazzite is now installed. Read the Post-Installation Guide for recommended next steps!</p>"},{"location":"General/Installation_Guide/legacy-install/","title":"Legacy ISO Installation Guide","text":""},{"location":"General/Installation_Guide/legacy-install/#legacy-isos-only","title":"Legacy ISOs Only","text":"<p>This guide is only for the legacy ISOs which are still supported at this time due to the new installer not supporting manual partitioning and some small bugs that are still present in the new installer.</p>"},{"location":"General/Installation_Guide/legacy-install/#system-requirements","title":"System Requirements","text":"<ul> <li>Read the Hardware Compatibility Guide for Bazzite's system requirements.</li> <li>Secure Boot and Trusted Platform Module (TPM) are supported on most hardware, but you must enroll our key during or after installation.</li> <li>Dual-booting with Windows is also supported.</li> </ul>"},{"location":"General/Installation_Guide/legacy-install/#installer-requirements","title":"Installer Requirements","text":"<ul> <li>A way to download the Bazzite ISO<ul> <li>A download manager (like Motrix) if the direct download for the Bazzite ISO fails or is downloading too slow.</li> </ul> </li> <li>A 16GB+ bootable medium like a Flash Drive<ul> <li>Software to flash the ISO like Fedora Media Writer (Windows/macOS or Linux)<ul> <li>Ventoy is NOT supported software for flashing the Bazzite ISO.</li> </ul> </li> </ul> </li> <li>A physical wired keyboard is recommended and required for devices without a touchscreen.<ul> <li>Otherwise, create a User Account with a username and a user password if you have a keyboard.</li> </ul> </li> </ul>"},{"location":"General/Installation_Guide/legacy-install/#desktop-environments","title":"Desktop Environments","text":"<p>All of the images come with the choice of KDE Plasma or GNOME for their desktop environment.</p> <p>Steam Gaming Mode is an option as an additional session in addition to KDE Plasma or GNOME and is recommended for Home Theatre PC (HTPC) and handheld setups.</p> <p>More information can be found on the Bazzite FAQ about the differences between the image variants.</p> KDE PlasmaGNOMESteam Gaming Mode"},{"location":"General/Installation_Guide/legacy-install/#kde-plasma-default","title":"KDE Plasma (Default)","text":"<ul> <li>KDE Plasma's default interface has a traditional and familiar layout</li> <li>Highly customizable with tons of settings</li> <li>Qt framework</li> <li>Popular Linux distributions like SteamOS use KDE Plasma</li> </ul>"},{"location":"General/Installation_Guide/legacy-install/#gnome-gnome-images","title":"GNOME (<code>-gnome</code> images)","text":"<ul> <li>GNOME's default interface has an elegant and touch-friendly layout</li> <li>Simple and concise</li> <li>GTK framework</li> <li>Popular Linux distributions like Ubuntu use GNOME</li> </ul>"},{"location":"General/Installation_Guide/legacy-install/#steam-gaming-mode-deck-images","title":"Steam Gaming Mode (<code>-deck</code> images)","text":"<p>Note</p> <p>Your device will automatically boot into the Steam Gaming Mode session at startup, and Desktop Mode can be accessed from the \"power menu\" in Steam Gaming Mode.</p> <ul> <li>Requires a Steam account</li> <li>Included in the Bazzite-Deck images</li> <li>Interface is designed for handheld and couch gaming</li> <li>Controller friendly</li> <li>Choice of KDE Plasma or GNOME as the Desktop Mode session</li> <li>Extra functionality with Decky plugins (See all plugins)</li> </ul>"},{"location":"General/Installation_Guide/legacy-install/#0-backup-data","title":"0. Backup Data","text":"<p>Make sure to backup your personal data from the drive you plan to install Bazzite on to a safe place before proceeding with the installation.</p>"},{"location":"General/Installation_Guide/legacy-install/#1-download-and-flash-legacy-iso","title":"1. Download and Flash Legacy ISO","text":"<ul> <li>Download Bazzite after choosing the correct ISO for your hardware with our Image Picker tool.</li> <li>Flash Bazzite to your bootable medium.</li> <li>Eject the drive after flashing the ISO.</li> </ul>"},{"location":"General/Installation_Guide/legacy-install/#calculating-iso-sha256-checksum-hash","title":"Calculating ISO SHA256 Checksum Hash","text":"<p>Video Tutorial:</p> <p></p>"},{"location":"General/Installation_Guide/legacy-install/#2-boot-bazzite","title":"2. Boot Bazzite","text":"<ul> <li>Connect your bootable medium to your device and boot into it.</li> <li>After connecting the device, boot into the Bazzite installer.</li> <li>This depends on your motherboard hardware, but most of the time it could be a function key like F9 or similar.<ul> <li>Sometimes you need to consult the manual, look up your device online, or read any hotkeys that appear when you boot your PC.<ul> <li>Alternatively change the BIOS settings to boot with your bootable device first before your current storage, but this is not recommended to keep enabled after installing Bazzite.</li> </ul> </li> </ul> </li> <li>Verify the media correctly and proceed to the installer.</li> </ul>"},{"location":"General/Installation_Guide/legacy-install/#handheld-devices","title":"Handheld Devices","text":"<p>Hold the 'Volume Down' (-) button and click the Power Button, and when you hear the chime, let go of both buttons, and you'll be booted into the Boot Manager. When you get to the boot menu, select your bootable device to boot into the Bazzite installer.</p>"},{"location":"General/Installation_Guide/legacy-install/#3-inside-the-installation-medium","title":"3. Inside the Installation Medium","text":"<p>Installing Bazzite without a physical keyboard connected to your device:</p> <p>If you do not have a USB physical keyboard connected, do NOT press \"User Creation\", since it will remove the default username and password, and you will be unable to type a username or password without a physical keyboard.</p> <p>default user: <code>bazzite</code> default password: <code>bazzite</code></p> <p></p> <p></p> <ul> <li>Select your language, region, keyboard layout, and time zone.</li> <li>Select the drive that Bazzite is going to be installed on.<ul> <li>Delete any partitions that you have remaining on the drive unless dual booting on the same drive.</li> <li>Recommended to use the automatic storage configuration unless dual booting on the same drive.</li> </ul> </li> <li>Optionally encrypt the drive with a password if desired.<ul> <li>If you lose this password, then it cannot be decrypted.</li> <li>A PHYSICAL WIRED KEYBOARD IS REQUIRED TO UNLOCK THE DEVICE!</li> </ul> </li> <li>Setup a user account.<ul> <li>Give administrative privileges and set a user password.</li> </ul> </li> <li>Begin the installation.</li> <li>Reboot device after it has finished installing.</li> </ul>"},{"location":"General/Installation_Guide/legacy-install/#dual-booting","title":"Dual Booting","text":"<p>Note</p> <p>Skip this section if you plan to install Bazzite without dual-booting Windows.</p>"},{"location":"General/Installation_Guide/legacy-install/#dual-booting-windows","title":"Dual-Booting Windows","text":"<p>For dual booting Windows on separate drives, use your motherboard's UEFI boot menu as the GRUB bootloader may not recognize each boot entry correctly.</p>"},{"location":"General/Installation_Guide/legacy-install/#video-walkthrough","title":"Video Walkthrough","text":""},{"location":"General/Installation_Guide/legacy-install/#written-walkthrough","title":"Written Walkthrough","text":"<ol> <li>Installing Bazzite with a shared drive.</li> <li>Installing Bazzite on a separate drive.</li> </ol> Shared Drive (Automatic Partitioning)Shared Drive (Manual Partitioning) [Only Available on Legacy ISO]Separate Drive <ol> <li>(In Windows) Disable Bitlocker encryption and fastboot, and reboot.</li> <li>(In Windows) Resize the Windows partition with the Disk Management app to have enough space for Bazzite. Usually should look something like this: Source: diskpart.com</li> <li>Run the Bazzite installer with the automatic partitioning option.</li> <li>Reboot into Bazzite and run <code>ujust regenerate-grub</code> in the terminal to add Windows to the GRUB.</li> </ol> <ol> <li>(In Windows) Resize the Windows partition with the Disk Management app to have enough space for Bazzite. Usually should look something like this: Source: diskpart.com</li> <li>Run the Bazzite installer with manual partitioning</li> <li>Reboot into Bazzite and run <code>ujust regenerate-grub</code> in the terminal to add Windows to the GRUB.</li> </ol> <p>When a dedicated drive is feasible, this method is recommended.</p> <p>Install Bazzite on a separate internal or external drive.</p> <ol> <li>Install the other operating system on a drive (like Windows).</li> <li>Install Bazzite on a second drive.</li> <li>Set Bazzite as the default in your boot order (optional).</li> </ol> <p>If you install Windows second, you should disconnect the Bazzite drive to prevent using the Windows installer of using its EFI partition.</p> <p>You can also install Windows to an external drive with Windows-to-Go using Rufus to dual boot if you do not have an internal drive available.</p> <p>If you install Windows after Bazzite, you can restore Bazzite's bootloader with the Bootloader Restoring Tool in the Live ISO.</p>"},{"location":"General/Installation_Guide/legacy-install/#manual-partitioning-instructions","title":"Manual Partitioning Instructions","text":"<p>Only users who are dual booting on the same drive should use these instructions. Automatic partitioning is preferred in other cases.</p> <p>Bazzite only supports the BTRFS filesystem for <code>/</code>.</p> <p>If you need a tutorial video for manual partitioning, watch this tutorial at timestamp 9:10.</p> <ol> <li>Select Installation Destination</li> <li>Select <code>Advanced Custom(Blivet-GUI)</code> under Storage Configuration. </li> <li>Create the following partitions and devices:<ul> <li>/boot/efi <pre><code>mount point: /boot/efi\nformat:      EFI system partition\nsize:        300MB\n</code></pre></li> <li>/boot <pre><code>mount point: /boot\nformat:      ext4\nsize:        2GB\n</code></pre></li> <li>btrfs partition <pre><code>mount point:\nformat: btrfs\nsize: [max]\n</code></pre></li> <li>/ <pre><code>mount point: /\nformat:      btrfs (subvolume)\n</code></pre></li> <li>/var <pre><code>mount point: /var\nformat:      btrfs (subvolume)\n</code></pre></li> <li>/var/home <pre><code>mount point: /var/home\nformat:      btrfs (subvolume)\n</code></pre></li> </ul> </li> <li>Select Done</li> <li>Select Accept Changes</li> <li>Continue with the installation.</li> </ol>"},{"location":"General/Installation_Guide/legacy-install/#dual-booting-other-linux-operating-systems","title":"Dual booting other Linux operating systems","text":"<p>Note</p> <p>Dual booting with other Linux distributions, especially non-atomic Fedora, is not officially supported. It is recommended to use your motherboard's UEFI boot menu or to forgo dual booting entirely to avoid unexpected issues. If something does go wrong, restore Bazzite's bootloader using the Bootloader Restoring Tool in the Live ISO.</p> <p>For Fedora Atomic Desktop images on the same drive: to dual boot another Fedora Atomic Desktop image (like Bluefin) installed alongside Bazzite, you must make an additional EFI partition and switch between them through your motherboard's UEFI boot menu.</p> <p>For dual booting on separate drives:</p> <p>Use your motherboard's UEFI boot menu as the GRUB bootloader may not recognize each boot entry correctly.</p>"},{"location":"General/Installation_Guide/legacy-install/#secure-boot","title":"Secure Boot","text":"<p>Note</p> <p>Skip this section if Secure Boot is not enabled or unsupported with your hardware.</p> <p>Important</p> <p>The enrollment prompt uses an English QWERTY keyboard layout, indiscriminately of your actual hardware keyboard. Other layouts can therefore interfere with the characters of the password (i.e. <code>A</code> and <code>Q</code> are swapped on AZERTY layouts).</p> <p>Bazzite supports Secure Boot however Universal Blue's key must be enrolled to use it otherwise keeping Secure Boot on in your BIOS will result in Bazzite not booting.</p>"},{"location":"General/Installation_Guide/legacy-install/#important-secure-boot-notes","title":"Important Secure Boot Notes:","text":"<ul> <li>Entering the password will register invisible characters for security purposes, so you will not be able to see what you are typing!</li> <li>Updating your BIOS may re-enable Secure Boot and you may have to follow \"Method B\" after updating it to resolve the black screen on boot complaining about loading the kernel first.</li> <li>The Steam Deck does not come with secure boot enabled and does not ship with any keys enrolled by default, do not enable Secure Boot on your Steam Deck unless you absolutely know what you're doing.</li> </ul>"},{"location":"General/Installation_Guide/legacy-install/#error-message-if-key-is-not-enrolled-properly","title":"Error Message (if key is not enrolled properly):","text":"<pre><code>error: ../../grub-core/kern/efi/sb.c:182:bad shim signature.\nerror: ../../grub-core/loader/1389/efi/linux.c:256:you need to load the kernel first.\n\nPress any key to continue...\n</code></pre> <p>Follow Method B below to resolve this and move past the error message if you encounter it.</p>"},{"location":"General/Installation_Guide/legacy-install/#method-a-during-installation-method","title":"Method A - During Installation Method","text":"<p>Note</p> <p>This screen will also appear on the next boot if you enable Secure Boot if it was disabled during installation.</p> <p>A blue screen will appear giving the option to enroll the signed keys after leaving the Bazzite installer.</p> <p><code>Enroll MOK</code> if you have secure boot enabled. If prompted to enter a password, then enter:</p> <pre><code>universalblue\n</code></pre> <p>Otherwise <code>Continue boot</code> if you have Secure Boot disabled or if it is not supported with your hardware.</p>"},{"location":"General/Installation_Guide/legacy-install/#method-b-after-installation-method","title":"Method B - After Installation Method","text":"<p>Disable Secure Boot in the BIOS before proceeding, and then re-enable it after enrolling the key.</p> <p>If you have already installed Bazzite then enter this command in a host terminal:</p> <pre><code>ujust enroll-secure-boot-key\n</code></pre> <p>If prompted to enroll the required key, then enter the password in the host terminal:</p> <pre><code>universalblue\n</code></pre> <p>You can now turn Secure Boot back on in the BIOS. Use the following command to boot straight into your system's BIOS (if supported):</p> <pre><code>ujust bios\n</code></pre>"},{"location":"General/Installation_Guide/legacy-install/#complete-mok-enrollment-at-boot","title":"Complete MOK enrollment at boot","text":"<p>On the next boot, you will see the blue MokManager screen:</p> <ol> <li>Choose Enroll MOK.</li> <li>When prompted for a password, enter: <pre><code>universalblue\n</code></pre></li> </ol> <p>After the reboot, the key is enrolled and Secure Boot can remain enabled. Your system should now boot normally under Secure Boot.</p>"},{"location":"General/Installation_Guide/legacy-install/#troubleshooting-installation","title":"Troubleshooting Installation:","text":"<p>Read the Troubleshooting Guide or the Alternative Installation Guide for installation workarounds.</p>"},{"location":"General/Installation_Guide/legacy-install/#post-installation","title":"Post-Installation","text":"<p>Bazzite is now installed. Read the Post-Installation Guide for recommended next steps or start gaming!</p>"},{"location":"General/Installation_Guide/post-installation/","title":"Post-Installation Setup","text":""},{"location":"General/Installation_Guide/post-installation/#first-boot-setup","title":"First Boot Setup","text":"<p>The first boot will show a screen showing your current and last deployment. It is important to note that the GRUB menu can be used to rollback Bazzite deployments if you encounter issues.</p> <p>Read more about this in the Updates, Rollback, and Rebasing documentation.</p>"},{"location":"General/Installation_Guide/post-installation/#setting-up-steam-gaming-mode-bazzite-deck-images-only","title":"Setting Up Steam Gaming Mode (Bazzite-Deck Images Only)","text":"<p>If you selected to use Steam Gaming Mode before downloading the ISO, then you will be on the Bazzite-Deck version.  After completing all of the above, then your next boot will be in Steam Gaming Mode which requires additional setup for Steam.</p> <p>Read the Bazzite-Deck documentation for more information on the HTPC/Handheld images.</p>"},{"location":"General/Installation_Guide/post-installation/#configure-system-settings","title":"Configure System Settings","text":"<p>It is important to configure the system settings on a first boot to personalize your desktop especially if you notice the scaling is incorrect on first-boot.  Open the system settings application in the desktop session to start configuring settings.</p>"},{"location":"General/Installation_Guide/post-installation/#scaling-settings","title":"Scaling Settings","text":"<p> KDE Plasma's System Settings application</p> <p> GNOME's Settings application</p> <p>Adjust the system settings to your preference.</p>"},{"location":"General/Installation_Guide/post-installation/#changing-default-password","title":"Changing Default Password","text":"<p><sub> (If it wasn't changed in the legacy ISO installer) </sub></p> <p></p> <p>Change it in the settings of Desktop Mode under the \"User\" category.</p>"},{"location":"General/Installation_Guide/post-installation/#dual-boot-post-configuration-setup","title":"Dual-Boot Post-Configuration Setup","text":"<p>Note</p> <p>This only applies to Bazzite users who are dual-booting with Windows.</p> <p>Show both your Windows and Bazzite installations in the GRUB menu to select from at boot by entering this command into the terminal:</p> <pre><code>ujust regenerate-grub\n</code></pre>"},{"location":"General/Installation_Guide/post-installation/#bazzite-as-primary-boot","title":"Bazzite as Primary Boot","text":"<p>If the <code>OS Boot Manager</code> has set <code>Windows Boot Manager</code> to be the first boot priority, then this may result in booting directly into Windows after the install instead of Bazzite. You may have to fix this in your BIOS settings.</p> <p>Take note that the GRUB menu might not show up. In such case, spam the \u2193 key when booting up.</p>"},{"location":"General/Installation_Guide/post-installation/#boot-into-windows-from-steam","title":"Boot into Windows from Steam","text":"<p>Adds a script in Steam to boot into Windows.</p> <pre><code>ujust setup-boot-windows-steam\n</code></pre>"},{"location":"General/Installation_Guide/post-installation/#expanding-storage-size-in-a-windows-dual-boot-scenario","title":"Expanding storage size in a Windows dual-boot scenario","text":"<p>Note</p> <p>This is for future reference after dual-booting for a while.</p> <p>Watch this video tutorial on how to expand the storage:</p> <p></p>"},{"location":"General/Installation_Guide/post-installation/#next-steps","title":"Next Steps","text":""},{"location":"General/Installation_Guide/post-installation/#configure-your-system-with-the-bazzite-portal-application","title":"Configure your system with the Bazzite Portal application","text":"<p>Familiarize yourself with the Bazzite Portal which does system maintenance, install a small subset of additional applications, and configure advanced system settings.</p>"},{"location":"General/Installation_Guide/post-installation/#install-additional-software-with-the-bazaar-app-store","title":"Install additional software with the Bazaar app store","text":"<p>Install additional software for Bazzite in the Bazaar app store.  This is the place where you will be getting most of your applications, but if you require something that isn't found here then look into the Installing and Managing Applications.</p>"},{"location":"General/Installation_Guide/post-installation/#ready-to-game","title":"Ready to Game","text":"<p>You have now installed Bazzite!</p> <p>Get started with gaming by reading our Gaming Guide which covers:</p> <ul> <li>Installing and configuring Steam and Proton for Windows game compatibility</li> <li>Setting up Lutris and other game launchers (Epic Games, GOG, Amazon Games, etc.)</li> <li>Managing and modding games</li> <li>Troubleshooting common gaming issues</li> </ul> <p>Enjoy Bazzite and make sure to report any bugs you encounter so they can be fixed ASAP if possible.</p>"},{"location":"General/Installation_Guide/troubleshoot_guide/","title":"Installation Troubleshooting","text":""},{"location":"General/Installation_Guide/troubleshoot_guide/#downloading-the-iso","title":"Downloading the ISO","text":"<p>Use a download manager (like Motrix) if the direct download fails or is downloading too slow.</p>"},{"location":"General/Installation_Guide/troubleshoot_guide/#drives","title":"Drives","text":"<p>Make sure to only select the appropriate drives to avoid losing data on others, and it is best practice to safely remove any external drives before proceeding.</p>"},{"location":"General/Installation_Guide/troubleshoot_guide/#failed-to-open-efibootmmx64efi-not-found-error","title":"\"Failed to open \\EFI\\BOOT\\mmx64.efi - Not Found\" error","text":"<p>To work around this issue, boot from file. Go into your UEFI (BIOS), select your EFI partition with Bazzite installed, then select /EFI/fedora/grubx64.efi to boot from. After this, your boot manager should boot normally showing \"FEDORA\" as the option.</p>"},{"location":"General/Installation_Guide/troubleshoot_guide/#installer-wont-boot","title":"Installer Won't Boot","text":"<p>Note</p> <p>The new installer may not boot if your BIOS is in CSM Legacy boot as opposed to UEFI. Read more in the Bazzite system requirements.</p> <p>Use the legacy ISO or try the alternative method of installing Bazzite.</p>"},{"location":"General/Installation_Guide/troubleshoot_guide/#error-code-1","title":"Error Code 1","text":"<p>The \"code 1\" error is a generic error code that appears during installation when a more specific error message isn't available. This error can occur in several scenarios that we have identified so far but there may be more scenarios:</p> <ul> <li>Existing Linux Installation: If you've previously installed another Linux on the same drive, the installer might fail when installing the bootloader with a 'bootloader write config' error.<ul> <li>This can happen even if the previous Linux installation is no longer functional. It is known to occur with both Fedora-based (Fedora, Fedora Atomic, Bazzite, Nobara, etc.) and Ubuntu-based (Ubuntu, Mint, PopOS, etc.) distros.</li> <li>Fix 1: Separate drive: If your hardware supports more than 1 SSD, install Bazzite on a different drive that has not seen Linux before.</li> <li>Fix 2: Manually remove the existing Linux from the EFI:  Please see below for instructions.</li> <li>Fix 3: Delete the existing EFI partition on the drive: If you are NOT planning on dual-booting, use GParted or Disks to remove the existing EFI.<ul> <li>Warning: This is irreversible and will remove every other operating system on the drive, including Windows</li> </ul> </li> <li>Fix 4: Create a new EFI partition: You can use manual partitioning as described in the Manual Partitioning Guide to create a new EFI partition alongside the existing one to accomplish this.<ul> <li>Warning: some BIOSes cannot handle a second EFI partition on the drive.</li> </ul> </li> </ul> </li> <li>Incorrect Filesystem: Using the EXT4 or any other filesystem type for the root partition will cause this error. You must use BTRFS for the root partition.</li> <li>Corrupted ISO Image: Ensure the ISO image isn't corrupted by calculating the checksums.</li> <li>Overheating USB Flash Drive: Use a USB 3.0 or better flash drive and plug it into a USB 3.0 or better port to avoid overheating.</li> </ul>"},{"location":"General/Installation_Guide/troubleshoot_guide/#no-space-left-on-device-error","title":"\"No Space left on Device\" Error","text":"<p>This error can misleadingly appear when the system does not have enough RAM for the installer to operate. You need at least 8GB of system memory to install Bazzite.</p>"},{"location":"General/Installation_Guide/troubleshoot_guide/#bad-shim-signature-you-need-to-load-the-kernel-first-error","title":"\"Bad shim signature, you need to load the kernel first\" error","text":"<p>Disable Secure Boot in BIOS to get past this screen. If you wish to use Secure Boot, follow the Secure Boot Guide using method B.</p> <p>Video Guide:</p> <p></p>"},{"location":"General/Installation_Guide/troubleshoot_guide/#device-is-active-error","title":"\"Device is Active\" Error","text":"<p>This error occurs when the installer encounters a BitLocker encrypted partition. You have two possible options:</p> <p>A. If Dual Booting: Shrink the partition in Windows before installing, enough to have enough room for a Bazzite install. B. Bazzite Only: Delete the BitLocker partition using a tool like GParted before installing.</p> <p>Watch this video for a demonstration:</p> <p></p>"},{"location":"General/Installation_Guide/troubleshoot_guide/#error-checking-storage-configuration","title":"\"Error checking storage configuration\"","text":"<p>Watch this video for a workaround:</p> <p></p>"},{"location":"General/Installation_Guide/troubleshoot_guide/#unable-to-allocate-requested-partition-scheme-error","title":"Unable to allocate requested partition scheme error","text":"<p>This error occurs when installing on drives larger than 2TB where the first 2TB or more is already occupied by one or more partitions. The image below illustrates the error message.</p> <p></p> <p>It seems like the Anaconda installer cannot create any partitions after the 2TB mark.</p> <p>Here are some possible solutions on how you can address it:</p> <ul> <li>Install Bazzite on a different storage device where Bazzite can have the entire drive.</li> <li>If you're dual booting with Windows, reduce the size of your Windows partition to under 2TB. If Windows' Disk Management can't do this, consider using a third-party tool like EaseUS Partition Master to resize the partitions while Windows is not running.</li> <li>If the drive contains no important data, you can delete all existing partitions and restart the installation process.</li> </ul>"},{"location":"General/Installation_Guide/troubleshoot_guide/#alternative-installation-method","title":"Alternative Installation Method","text":"<p>Note</p> <p>The alternative installation method is useful for downloading a smaller ISO and may resolve other issues, but also contains display issues in the installer on most handheld displays.</p> <p>If none of the above errors are relevant to your issue, or you still have problems installing Bazzite, then try following our alternative installation method:</p> <p>Try installing Bazzite by rebasing from Fedora Kinoite (KDE Plasma) or Fedora Silverblue (GNOME).</p>"},{"location":"General/Installation_Guide/troubleshoot_guide/#how-to-remove-an-orphaned-copy-of-grub","title":"How to remove an orphaned copy of GRUB","text":"<ol> <li>Boot into the Bazzite installer (the Legacy Installer will not work for this) and open the Application Menu </li> <li>Type 'disk' and open the Disks app </li> <li>Select the drive you want to install Bazzite on </li> <li>Identify your EFI partition, it will be of filesystem type FAT and typically very small </li> <li>Mount the EFI partition (if it's not already mounted) by clicking on the Play button </li> <li>Click on the blue writing next to 'mounted at' </li> <li>Double-click on the EFI folder </li> <li>Identify the 'Ubuntu' or 'Fedora' folder and move it to the trashcan </li> </ol> <p>Warning</p> <p>Do not remove any other folders, such as Boot, Dell, HP, or Microsoft, or Windows may fail to boot properly!</p> <ol> <li>Reboot, and run the installer again. You might want to delete the partitions that were created during the first install attempt. </li> </ol>"},{"location":"Handheld_and_HTPC_edition/","title":"Bazzite-Deck Guides","text":"<ul> <li>Bazzite-Deck General Overview</li> <li>Steam Gaming Mode Quirks and Workarounds</li> <li>Handheld Compatibility<ul> <li>ASUS Handhelds</li> <li>Lenovo Handhelds</li> <li>GPD Handhelds</li> <li>OneXPlayer Handhelds</li> <li>Ayn Handhelds</li> <li>Ayaneo Handhelds</li> <li>Steam Deck</li> <li>Other Handhelds</li> </ul> </li> </ul>"},{"location":"Handheld_and_HTPC_edition/Steam_Gaming_Mode/","title":"Bazzite-Deck General Overview","text":""},{"location":"Handheld_and_HTPC_edition/Steam_Gaming_Mode/#what-is-bazzite-deck","title":"What is Bazzite-Deck?","text":"<p>Bazzite for Home Theater PC setups and Handheld PCs.  It is intended to be a controller-friendly environment and give users a \"console-like\" experience similar to SteamOS for the Steam Deck. It is intended for both handhelds and home theatre PC setups. Bazzite is similar to SteamOS by sharing many packages that SteamOS includes, so it is ready to game as soon the installation process is finished.</p> <p>This documentation may not cover specific areas with the assumption that the user is already aware of SteamOS and how it works. If you are unfamiliar with something that cannot be found in our documentation, then research your specific question with \"SteamOS\" or \"Steam Deck\" as keywords in your search. Otherwise, ask your question on our forums or Discord.</p>"},{"location":"Handheld_and_HTPC_edition/Steam_Gaming_Mode/#what-is-steam-gaming-mode","title":"What is Steam Gaming Mode?","text":"<p>View the Handheld Documentation for post-installation setup and common issues on handheld hardware.</p> <p></p> <p><sub>Please note that Steam Gaming Mode has demanding GPU hardware requirements compared to traditional desktop environments.</sub></p> <p>Important</p> <p>The Steam beta client is not supported, please revert to the stable client before reporting issues.</p> <p> <sub>Steam Deck UI Tour by Linux For Everyone</sub></p> <p>Bazzite utilizes Steam Gaming Mode to fill the niche of handheld and couch gaming setups. Steam Gaming Mode is what SteamOS on the Steam Deck is built around. A simple interface that is controller-friendly built around Steam's \"Big Picture Mode\" UI/UX. The minimal session only runs the bare minimum in the background, so most of the hardware resources is going towards the game being played. </p> <p>Gamescope is the main ingredient in Steam Gaming Mode which gives options to set a framerate cap, resolution scaling options, etc. Steam Gaming Mode is also referred to as \"gamepadUI\" and \"gamescope-session\" but Bazzite documentation will usually refer to it as \"Steam Gaming Mode\" for consistency.</p>"},{"location":"Handheld_and_HTPC_edition/Steam_Gaming_Mode/#steam-input","title":"Steam Input","text":"<p>Note</p> <pre><code>Some games and emulators may need Steam Input **disabled** to work correctly with your controls.\n</code></pre> <p>A Steam guide that goes over tips and tricks for controls on the Steam Deck, but contains information that can still apply to all devices running Bazzite-Deck.</p>"},{"location":"Handheld_and_HTPC_edition/Steam_Gaming_Mode/#how-do-i-open-the-side-menus-with-a-physical-keyboard","title":"How do I open the side menus with a physical keyboard?","text":"<p>Steam Home Menu: Ctrl/Win+1 Quick Access Menu (QAM): Ctrl/Win+2</p>"},{"location":"Handheld_and_HTPC_edition/Steam_Gaming_Mode/#valves-official-steamos-guide","title":"Valve's Official SteamOS Guide","text":"<p>Important</p> <p>Not all of the information will be accurate in regards to Bazzite-Deck.</p> <p>Valve wrote a guide for the Steam Deck which may have some relevant information in regards to Bazzite.</p>"},{"location":"Handheld_and_HTPC_edition/quirks/","title":"Steam Gaming Mode Quirks and Workarounds","text":""},{"location":"Handheld_and_HTPC_edition/quirks/#how-do-i-use-my-microsd-card-that-i-used-on-my-steam-deck-running-steamos","title":"How do I use my microSD card that I used on my Steam Deck running SteamOS?","text":"<p>Open a host terminal and enter this command:</p> <pre><code>ujust switch-to-ext4\n</code></pre>"},{"location":"Handheld_and_HTPC_edition/quirks/#how-do-i-specify-the-correct-monitor-for-gaming-mode-to-use-htpc-only","title":"How do I specify the correct monitor for Gaming Mode to use? (HTPC only)","text":"<p>In Desktop Mode, open a host terminal and run this command:</p> <pre><code>mkdir ~/.config/environment.d\nnano ~/.config/environment.d/10-gamescope-session.conf\n</code></pre> <p>Then add this to the file:</p> <p><code>OUTPUT_CONNECTOR=DP-1</code> Change <code>DP-1</code> to the correct output. You can find your display outputs using the command</p> <p>KDE: <pre><code>kscreen-doctor -o\n</code></pre></p> <p>GNOME: <pre><code>gnome-randr\n</code></pre></p> <p>Note</p> <p>It has been reported that some systems dont properly report the Display Output name when using gnome-randr, you can run the command below to list all the connected output names without any details so that you can compare them with what the above commands report.</p> <pre><code>grep -r '^connected' /sys/class/drm/*/status | grep -Po 'card.?-\\K([^/]*)'\n</code></pre> <p>Save with CTRL + X then pressing Y followed by ENTER</p>"},{"location":"Handheld_and_HTPC_edition/quirks/#audio-output-not-working-default-device","title":"Audio output not working (Default Device)","text":"<p>This issue happens usually with HDMI TV audio.  Go into Desktop Mode and into the system settings to adjust the sound settings. Disable devices that do not match the sound output that you're using. An example of this is disabling all the things that aren't HDMI for your TV audio.</p>"},{"location":"Handheld_and_HTPC_edition/quirks/#change-physical-keyboard-layout-for-steam-gaming-mode","title":"Change physical keyboard layout for Steam Gaming Mode","text":"<p>Steam Gaming Mode has no official way to change the physical keyboard layout and will always default to the US layout.  If you want to change the layout, then you can set the environment variable <code>XKB_DEFAULT_LAYOUT=no</code> replacing <code>no</code> with the correct layout for you.</p> <p>Add this environment variable to <code>~/.config/environment.d/10-gamescope-session.conf</code> Basically, make sure hidden files is turned on and move into the Home directory, then go into the .config directory and enter the environment.d directory.  Inside that directory, the file that should be edited with a text editor should be saved as \"10-gamescope-session.conf\" for it to work properly.</p> <p><sub>(Please note, if both the \"10-gamescope-session.conf\" file and/or \"environment.d\" folder does not exist already, then create it.)</sub></p> <p>This works in Desktop Mode including running Nested Gamescope and also works for Nested Desktop, but it has its own quirks: altgr + 2 to write \"@\" on the Norwegian layout will still not work, but the basic keyboard layout will always work.  The <code>altgr</code> key is luckily not needed for normal typing on the Norwegian layout, however altgr has been reported to work on the French layout, but your mileage may vary.</p>"},{"location":"Handheld_and_HTPC_edition/quirks/#how-do-i-disable-certain-steam-deck-features-that-conflict-with-my-setup","title":"How do I disable certain \"Steam Deck\" features that conflict with my setup?","text":"<p>Scenarios where this is desirable:</p> <p>&gt; Example 1: Keyboard and mouse is not working for this title.</p> <p>&gt; Example 2: The game\u2019s launcher for adjusting video settings or adding mods does not launch.</p> <p>&gt; Example 3: Certain features/options are not available that should be.</p> <p>Open the game's properties on Steam and enter this launch option:</p> <pre><code>SteamDeck=0 %command%\n</code></pre>"},{"location":"Handheld_and_HTPC_edition/quirks/#why-do-specific-decky-loader-plugins-not-function-on-bazzite","title":"Why do specific Decky Loader plugins not function on Bazzite?","text":"<p>Some plugins are built specifically for SteamOS or the Steam Deck, and won\u2019t necessarily work on Bazzite or non-Steam-Deck hardware.</p> <p>For example, the DeckMTP plugin only works on the Steam Deck models and will not work on other hardware.</p>"},{"location":"Handheld_and_HTPC_edition/quirks/#how-do-i-use-steamdeckgyrodsu-on-hardware-that-isnt-the-steam-deck","title":"How do I use SteamDeckGyroDSU on hardware that isn't the Steam Deck?","text":"<p>You cannot use SteamDeckGyroDSU outside of the Steam Deck, but you can try disabling Steam Input and it may work depending on your hardware and use case.</p>"},{"location":"Handheld_and_HTPC_edition/quirks/#how-do-i-specify-which-gpu-that-steam-gaming-mode-should-use","title":"How do I specify which GPU that Steam Gaming Mode should use?","text":"<p>Open a TTY session with an external physical keyboard using this keyboard combination: Ctrl+Alt+F4</p> <pre><code>export-gpu\n</code></pre> <p>Alternatively, in Desktop Mode, enter this command in the terminal:</p> <pre><code>/usr/bin/export-gpu\n</code></pre> <p>Select the GPU to use for Steam Gaming Mode.</p>"},{"location":"Handheld_and_HTPC_edition/quirks/#i-lost-my-return-to-gaming-mode-shortcut","title":"I lost my \"Return to Gaming Mode\" shortcut","text":"<p>You can restore this shortcut by opening terminal and running:</p> <pre><code>ujust restore-gamemode-shortcut\n</code></pre>"},{"location":"Handheld_and_HTPC_edition/quirks/#cannot-progress-past-this-screen","title":"Cannot progress past this screen","text":"<p> 1.  Open a TTY session with an external physical keyboard using this keyboard combination: Ctrl+Alt+F4 2.  Login to your user. 3.  Enter this command: <pre><code>steamos-session-select plasma\n</code></pre> 4. Log into Steam in Desktop mode, and reboot the device.</p>"},{"location":"Handheld_and_HTPC_edition/quirks/#stuck-on-update-calculating-time-remaining","title":"Stuck on 'Update calculating: Time Remaining'","text":"<p> Reboot the device.</p>"},{"location":"Handheld_and_HTPC_edition/quirks/#steam-broke-and-gaming-mode-is-broken-too","title":"Steam broke and Gaming Mode is broken too","text":"<p>In scenarios where Steam Gaming Mode refuses to start due to an issue with the Steam client.</p>"},{"location":"Handheld_and_HTPC_edition/quirks/#desktop-mode-method","title":"Desktop Mode Method","text":"<p>Open a host terminal and enter this command:</p> <pre><code>ujust fix-reset-steam\n</code></pre>"},{"location":"Handheld_and_HTPC_edition/quirks/#tty-method-if-you-cannot-access-desktop-mode","title":"TTY Method (if you cannot access Desktop Mode)","text":"<p>Access a TTY session with Ctrl+Alt+F4 and login with your Bazzite username and password.</p> <p>Enter this command:</p> <pre><code>ujust fix-reset-steam\n</code></pre>"},{"location":"Handheld_and_HTPC_edition/quirks/#something-went-wrong-while-displaying-this-content-error","title":"\"Something went wrong while displaying this content\" Error","text":"<p>This is most likely due to a broken Decky Loader plugin you have installed. Uninstall the broken plugin. Specific CSS Loader themes can also cause this issue.</p>"},{"location":"Handheld_and_HTPC_edition/quirks/#why-is-vrr-not-working-on-my-vrr-compatible-display","title":"Why is VRR not working on my VRR-compatible display?","text":"<p>Most of the time this is because you're connecting the device via HDMI which does not support VRR on Linux. Here is the source of that information.</p>"},{"location":"Handheld_and_HTPC_edition/quirks/#rainbow-display","title":"Rainbow Display","text":"<p>Toggle HDR on and off in the Quick Access Menu.</p> <p>However, you may need to enable \"Force Composite\" found in the Developer Options, which also has to be enabled in the Steam settings beforehand.</p>"},{"location":"Handheld_and_HTPC_edition/quirks/#stuck-at-the-bazzite-logo","title":"Stuck at the Bazzite logo","text":"<ol> <li>Opening a TTY session with an external physical keyboard using this keyboard combination and entering this command: Ctrl+Alt+F4</li> <li>Login to your user.</li> <li>Enter this command: <pre><code>ujust fix-reset-steam\n</code></pre></li> </ol> <p>Reboot the system.</p>"},{"location":"Handheld_and_HTPC_edition/quirks/#alternative-method","title":"Alternative Method","text":"<p>Attention</p> <p>Try rebooting your device first before proceeding with the next steps! You may lose your games, saves, and other content if this is done incorrectly.</p> <ol> <li>Open a TTY session with an external physical keyboard using this keyboard combination and entering this command: Ctrl+Alt+F4 and <code>mv ~/.local/share/Steam ~/.local/share/Steam1</code></li> <li>This command will rename the <code>Steam</code> directory to <code>Steam1</code>, and it will force Steam to reinitialize and create a new directory.</li> <li>You can move your games from the renamed <code>Steam1</code> directory to the new <code>Steam</code> directory if you had any installed previously on your internal storage.</li> <li>Exit the TTY session by entering this keyboard combination: Ctrl + Alt + F2.</li> </ol>"},{"location":"Handheld_and_HTPC_edition/quirks/#video-tutorial","title":"Video Tutorial","text":""},{"location":"Handheld_and_HTPC_edition/quirks/#nvidia-gpu-exclusive-issues-with-steam-gaming-mode","title":"Nvidia GPU Exclusive Issues with Steam Gaming Mode","text":"<ul> <li>\"Enable GPU accelerated rendering in web views (requires restart)\" must be enabled in the Steam settings for better performance in the UI.<ul> <li>Resolutions above 2560x1440 will cause game-breaking graphical artifacts using this setting.</li> </ul> </li> <li>HDR can cause game-breaking graphical artifacts.</li> </ul>"},{"location":"Handheld_and_HTPC_edition/Handheld_Wiki/","title":"Handheld Compatibility","text":""},{"location":"Handheld_and_HTPC_edition/Handheld_Wiki/#steamos-like-functionality","title":"SteamOS-like Functionality","text":"<p>Notice: Bazzite uses Handheld Daemon for proper handheld support currently. </p> <p>Bazzite-Deck images ship with Steam Gaming Mode which is intended to mimic the experience of SteamOS.  The goal is to have earlier support for most x86_64 handheld PCs before SteamOS and with the same benefits of the desktop version of Bazzite.</p>"},{"location":"Handheld_and_HTPC_edition/Handheld_Wiki/#supported-handhelds","title":"Supported Handhelds","text":"<p>Attention</p> <p>This list is incomplete and does not indicate that unlisted handhelds do not work with Bazzite currently, but because we lack specific information regarding their post-installation setup, workarounds, and proper hardware support for Linux, they are unlisted here.</p> <p>All handhelds except for the Steam Deck make use of Handheld Daemon for controls, TDP, etc.</p> <p>Click the name of each hardware to view post-installation setup and known issues/workarounds.</p> <ul> <li>ASUS Handhelds</li> <li>Lenovo Handhelds</li> <li>GPD Handhelds</li> <li>OneXPlayer Handhelds</li> <li>Ayn Handhelds</li> <li>Ayaneo Handhelds</li> <li>Steam Deck</li> <li>Other Handhelds</li> </ul> <p>If your handheld isn't listed in the entries, then it does not necessarily mean that the device is unsupported. </p>"},{"location":"Handheld_and_HTPC_edition/Handheld_Wiki/#hhd-setup","title":"HHD Setup","text":"<p>Attention</p> <p>HHD is intended and functional for handhelds that are not the Steam Deck.</p> <p>Read the HHD README for more information.</p> <ol> <li> <p>Double press the 'side menu button' to access Handheld Daemon overlay in Steam Gaming Mode</p> </li> <li> <p>Select the controller emulation and RGB color you want</p> </li> </ol> <p>Note</p> <p>Gyro functionality requires DualSense emulation</p>"},{"location":"Handheld_and_HTPC_edition/Handheld_Wiki/#tdp-controls","title":"TDP Controls","text":"<p>There are a few options for TDP Controls that work with Bazzite:</p> <ul> <li>The HHD-overlay supports TDP controls. (Primary Supported Method)<ul> <li>Also has a desktop app that is pre-installed, look for the Handheld Daemon app in Desktop Mode.</li> </ul> </li> <li>SimpleDeckyTDP supports TDP, GPU, Power Governor, and among other settings.<ul> <li>Also has a graphical application, but needs to be manually installed.</li> <li>PowerControl supports TDP, GPU, and fan controls on select devices.</li> </ul> </li> </ul>"},{"location":"Handheld_and_HTPC_edition/Handheld_Wiki/#how-do-i-open-the-hhd-overlay","title":"How do I open the HHD Overlay?","text":"<p>Press, hold, or double-tap the Quick Access Menu button.</p>"},{"location":"Handheld_and_HTPC_edition/Handheld_Wiki/#controller-information","title":"Controller Information","text":"<p>For most handheld hardware, besides the Steam Deck, emulation of a DualSense controller is used for full functionality. Double tap or hold the side menu button to access settings for controller emulation including switching to an Xbox controller with reduced functionality.</p> <p>If your device has paddles, you will want to use the DualSense Edge controller (excluding the Ayn Loki). It\u2019s disabled by default because some games do not map it correctly.</p> <p>Some games and emulators may need Steam Input disabled to work correctly with your controls.</p>"},{"location":"Handheld_and_HTPC_edition/Handheld_Wiki/#desktop-controls","title":"Desktop Controls","text":"<p>Desktop controller layout may not exist by default if Steam doesn't setup your handheld controller properly. This can be fixed in Steam's controller settings.</p> <p>The virtual keyboard is Steam's on-screen keyboard, but needs to be setup in Steam's settings in Desktop Mode. There is no default keybinding for Steam's on-screen keyboard (Remap it to X or whatever you prefer).  Desktop controller layout may not exist by default if Steam doesn't setup your handheld controller properly. This can be fixed in Steam's controller settings</p>"},{"location":"Handheld_and_HTPC_edition/Handheld_Wiki/#decky-setup","title":"Decky Setup","text":"<p>To install Decky Loader, open a host terminal and enter:</p> <pre><code>ujust setup-decky\n</code></pre> <p>You can access Decky Loader by pressing the 'side menu button', also known as the Quick Access Menu (QAM), once from within Steam Gamemode or Steam Big Picture Mode.</p> <p>The Quick Access Menu is accessible from the keyboard with Control + 2, or with an external controller using Xbox/PS button + A/X.</p>"},{"location":"Handheld_and_HTPC_edition/Handheld_Wiki/#decky-plugins","title":"Decky Plugins","text":"<p>Attention</p> <p>Decky may break or uninstall after updates especially if there is an update.</p> <p>Install optional Decky plugins for your handheld. If you experience any major issues then it is recommended to uninstall Decky before reporting Bazzite bugs.</p>"},{"location":"Handheld_and_HTPC_edition/Handheld_Wiki/#unsupported-handhelds","title":"Unsupported Handhelds","text":"<p>Note</p> <p>Certain handhelds have been confirmed to boot Bazzite, but are plagued by missing driver support for Linux including missing audio drivers.</p> <p>Unsupported handhelds could work with Bazzite, but there may be major issues encountered that are undocumented. If your handheld hardware is not listed, then you can still give Bazzite a try with our Bazzite-Deck image.</p> <p>Your mileage may vary with untested hardware. Bazzite does not have the required setup for unsupported handheld, so setup will be manually done by the end-user for different functionality if it even works properly on the unsupported device.</p>"},{"location":"Handheld_and_HTPC_edition/Handheld_Wiki/#e-gpu-caveats","title":"e-GPU Caveats:","text":"<ul> <li>The same GPU hardware requirements that apply for Steam Gaming Mode also apply for e-GPUs.<ul> <li>Nvidia GPUs are unsupported but may work if rebasing to a Nvidia <code>-deck</code> image with a potential for outstanding bugs.</li> </ul> </li> </ul> <p>General Linux e-GPU Guide + Script</p>"},{"location":"Handheld_and_HTPC_edition/Handheld_Wiki/ASUS_ROG_Ally/","title":"ASUS Handhelds","text":"<p>Disclaimer</p> <p>This wiki may contain outdated information.</p>"},{"location":"Handheld_and_HTPC_edition/Handheld_Wiki/ASUS_ROG_Ally/#asus-rog-ally-asus-rog-ally-x","title":"ASUS ROG Ally / ASUS ROG Ally X","text":""},{"location":"Handheld_and_HTPC_edition/Handheld_Wiki/ASUS_ROG_Ally/#general-notes","title":"General Notes","text":"<ul> <li>Holding the Armoury Crate button (on the side) allows you to switch to Mouse Mode</li> <li>Enable the Steam Power Button Handler setting in Handheld Daemon</li> </ul>"},{"location":"Handheld_and_HTPC_edition/Handheld_Wiki/ASUS_ROG_Ally/#optional-tweaks","title":"Optional Tweaks","text":"<ul> <li>Adjust settings in Handheld Daemon.</li> <li>Adjust the scaling of the UI in the Display Settings.</li> </ul>"},{"location":"Handheld_and_HTPC_edition/Handheld_Wiki/ASUS_ROG_Ally/#known-issues","title":"Known Issues","text":"<ul> <li>Changing A/C power sometimes leads to a stuck TDP.</li> <li>Some users report the mic sounding garbled<ul> <li>Solution to that is to set the mic/input volume to 10%-15% in settings</li> <li>For Discord you also need to set the input profile in the Discord Settings to voice cancellation.</li> </ul> </li> <li>(Xbox Ally Only) Audio swaps from left to right internal speakers as mono.<ul> <li>This is a known problem that is supposed to be fixed on Kernel 6.19</li> </ul> </li> <li>Some users report that \"Auto UMA\" in the bios can cause crashes in some games.<ul> <li>If you encounter this, then try setting the VRAM in bios to 4GB or 8GB.</li> </ul> </li> <li>LED indicator is on max brightness by default and cannot be changed on any other operating system outside of Windows.<ul> <li>This is tied to the firmware.</li> <li>This also affects when the ally is charging and sleeping.</li> </ul> </li> <li>The Ally does not support button holding for the Steam or QAM buttons.<ul> <li>Steam Input's chords do not work by default.<ul> <li>Swapping the Start/Select button(s) is a workaround.</li> </ul> </li> </ul> </li> <li>Suspend can break if SMT is disabled</li> <li>Fingerprint driver does not work.</li> <li>Storage shows duplicate drives.<ul> <li>This is a visual bug, do not attempt to format this drive!</li> </ul> </li> <li>Turning on the wake animation when resuming from sleep causes the device to act erratically.<ul> <li>No controls outside of Steam.</li> <li>Steam's top and bottom panels missing.</li> </ul> </li> </ul>"},{"location":"Handheld_and_HTPC_edition/Handheld_Wiki/ASUS_ROG_Ally/#cpu-boost","title":"CPU Boost?","text":"<p>Disabled by default to prevent excessive power draw to the device.</p> <p>More information can be found here about this.</p>"},{"location":"Handheld_and_HTPC_edition/Handheld_Wiki/Ayaneo_Handhelds/","title":"Ayaneo Handhelds","text":"<p>Disclaimer</p> <p>Sleep functionality requires a BIOS update.</p>"},{"location":"Handheld_and_HTPC_edition/Handheld_Wiki/Ayaneo_Handhelds/#ayaneo-geek-1s","title":"Ayaneo Geek 1S","text":""},{"location":"Handheld_and_HTPC_edition/Handheld_Wiki/Ayaneo_Handhelds/#known-issues","title":"Known Issues","text":"<ul> <li>Suspending the device requires the latest BIOS update.<ul> <li>Reports of controller issues on wake have reported inconsistency. Enabling \"full initial usb support\" in Bios seems to have an impact on how frequent the issue is.</li> </ul> </li> <li>VRAM size option is missing from BIOS as it's controlled by AYASPACE application under windows. You can change the amount of UMA buffer size using Smokeless_UMAF, but this method has its own associated risks.</li> </ul>"},{"location":"Handheld_and_HTPC_edition/Handheld_Wiki/Ayaneo_Handhelds/#functional-hhd","title":"Functional HHD","text":"<pre><code>sudo systemctl enable --now hhd@$(whoami)\n</code></pre>"},{"location":"Handheld_and_HTPC_edition/Handheld_Wiki/Ayaneo_Handhelds/#e-gpu-support","title":"e-GPU Support:","text":"<ul> <li>e-GPU Thunderbolt \u00be and USB4 enclosures over USB4 are supported.<ul> <li>AMD:<ul> <li>Automatic switch at boot with all-ways-egpu works fine using method 2 and 3 at boot, unfortunately method 1 is not supported.<ul> <li>The script needs to be installed with Steam Deck/User Installation.</li> </ul> </li> <li>No issue in booting with eGPU attached. Tested on RX 6800 and no kernel parameters are needed since Bazzite is now enabling the needed argument by default (amdgpu .ppfeaturemask).<ul> <li>Using <code>rpm-ostree kargs --append-if-missing=pci=nommconf</code> (or editing the kernel command line with <code>rpm-ostree kargs \u2013editor</code>) is still needed according to my testing because some applications otherwise may underperform.</li> </ul> </li> <li>Some AMD cards requires to set a correct limit for GPU and Memory Clocks, this is a known issue that is present also on Desktops. I suggest installing LACT and setting the correct limits for the card.</li> </ul> </li> <li>NVIDIA: currently untested but may work with the \u201c-nvidia-deck\u201d variant of bazzite.</li> </ul> </li> </ul>"},{"location":"Handheld_and_HTPC_edition/Handheld_Wiki/Ayaneo_Handhelds/#external-resource","title":"External Resource","text":"<p>Check out the original thread for more information and updates on this device.</p> <p>Ayaneo Geek 1s is (as of April 2025) the only Ryzen 7000 handheld which is yet to receive the EC update that increase battery life. You can follow and report on this discord thread.</p>"},{"location":"Handheld_and_HTPC_edition/Handheld_Wiki/Ayn_Handhelds/","title":"Ayn Handhelds","text":"<p>Disclaimer</p> <p>This wiki may contain outdated information.</p>"},{"location":"Handheld_and_HTPC_edition/Handheld_Wiki/Ayn_Handhelds/#ayn-loki-max","title":"Ayn Loki Max","text":""},{"location":"Handheld_and_HTPC_edition/Handheld_Wiki/Ayn_Handhelds/#optional-tweaks","title":"Optional Tweaks","text":"<ul> <li>Adjust RGB with Steam Gaming Mode under <code>Settings &gt; Controller &gt;  Calibration &amp; Advanced &gt; LED Settings</code> or in Handheld Daemon</li> <li>Adjust the scaling of the UI in the Display Settings</li> <li>Set a charge limit in HHD with Handheld Daemon</li> </ul>"},{"location":"Handheld_and_HTPC_edition/Handheld_Wiki/Ayn_Handhelds/#known-issues","title":"Known Issues","text":"<ul> <li>Games can sometimes default to 800p resolution.<ul> <li>Manually change the resolution per game in the <code>Steam Settings &gt; Properties &gt; Game Resolution</code> to either \"Native\" or other higher resolutions.</li> </ul> </li> <li>Back buttons are hard mapped to L3 and R3.<ul> <li>This is also an issue on Windows.</li> </ul> </li> </ul>"},{"location":"Handheld_and_HTPC_edition/Handheld_Wiki/Ayn_Handhelds/#ayn-loki-mini-pro","title":"Ayn Loki Mini Pro","text":""},{"location":"Handheld_and_HTPC_edition/Handheld_Wiki/Ayn_Handhelds/#optional-tweaks_1","title":"Optional Tweaks","text":"<ul> <li>Adjust RGB with Steam Gaming Mode under <code>Settings &gt; Controller &gt;  Calibration &amp; Advanced &gt; LED Settings</code> or in Handheld Daemon</li> <li>Adjust the scaling of the UI in the Display Settings</li> <li>Set a charge limit in HHD with Handheld Daemon</li> </ul>"},{"location":"Handheld_and_HTPC_edition/Handheld_Wiki/Ayn_Handhelds/#known-issues_1","title":"Known Issues","text":"<ul> <li>Games can sometimes default to 800p resolution.<ul> <li>Manually change the resolution per game in the <code>Steam Settings &gt; Properties &gt; Game Resolution</code> to either <code>Native</code> or other higher resolutions.</li> </ul> </li> <li>Audio driver does not currently work.<ul> <li>No internal audio in either Gaming Mode or Desktop Mode.<ul> <li>External audio is reported to have low sound quality.</li> </ul> </li> </ul> </li> <li>Rotation is wrong in Desktop Mode for KDE images.</li> <li>Mouse input may break in Desktop Mode.</li> </ul>"},{"location":"Handheld_and_HTPC_edition/Handheld_Wiki/GPD_Handhelds/","title":"GPD Handhelds","text":"<p>Disclaimer</p> <p>This wiki may contain outdated information.</p>"},{"location":"Handheld_and_HTPC_edition/Handheld_Wiki/GPD_Handhelds/#gpd-win-4","title":"GPD Win 4","text":""},{"location":"Handheld_and_HTPC_edition/Handheld_Wiki/GPD_Handhelds/#general-information-optional-tweaks","title":"General Information &amp; Optional Tweaks","text":"<ul> <li>Adjust RGB with Steam Gaming Mode in Handheld Daemon</li> <li>Adjust the scaling of the UI in the Display Settings</li> <li>Set a charge limit in HHD with Handheld Daemon</li> <li>GPD devices also have a physical switch you can toggle to enable a separate desktop/mouse mode.</li> </ul>"},{"location":"Handheld_and_HTPC_edition/Handheld_Wiki/GPD_Handhelds/#known-issues","title":"Known Issues","text":"<ul> <li>Suspend-resume fully works on the 6800u Win 4 after disabling the fingerprint scanner, but there are a few user reports of the 7840u and newer models having only partially working suspend-resume.<ul> <li>It seems to be very similar/related to the suspend issue on the GPD WM2 7840u and newer devices, more details here</li> </ul> </li> <li>Games can sometimes default to 800p resolution.<ul> <li>Manually change the resolution per game in the <code>Steam Settings &gt; Properties &gt; Game Resolution</code> to either <code>Native</code> or other higher resolutions.</li> </ul> </li> <li>Back buttons may need to be manually remapped before they are usable.<ul> <li>Manually remap back buttons as described in hhd docs here<ul> <li>Watch this video if you need a visual guide.</li> </ul> </li> </ul> </li> </ul>"},{"location":"Handheld_and_HTPC_edition/Handheld_Wiki/GPD_Handhelds/#external-resource","title":"External Resource","text":"<p>For more information, check out the GPD Win Tips and Tricks guide which includes useful scripts for this handheld.</p>"},{"location":"Handheld_and_HTPC_edition/Handheld_Wiki/GPD_Handhelds/#gpd-win-max-2","title":"GPD Win Max 2","text":""},{"location":"Handheld_and_HTPC_edition/Handheld_Wiki/GPD_Handhelds/#optional-tweaks","title":"Optional Tweaks","text":"<ul> <li>Steam Gaming Mode Display settings that are recommended to be changed:<ul> <li><code>Use Native Color Temperature</code> - Enabled</li> </ul> </li> <li>GPD devices also have a physical switch you can toggle to enable a separate desktop/mouse mode</li> <li>Adjust RGB with Steam Gaming Mode in Handheld Daemon</li> <li>Adjust the scaling of the UI in the Display Settings</li> <li>Set a charge limit in HHD with Handheld Daemon</li> </ul>"},{"location":"Handheld_and_HTPC_edition/Handheld_Wiki/GPD_Handhelds/#known-issues_1","title":"Known Issues","text":"<ul> <li>Suspend-resume works on the WM2 6800u model after disabling the fingerprint scanner, but 7840u and newer models have only partially working suspend-resume.<ul> <li>Read about the issue here for details on suspend-resume issues for the newer WM2 devices.</li> </ul> </li> <li>If you install your OS on an m2 2230 SSD in the secondary drive slot, it can cause suspend issues.<ul> <li>You should install your OS onto the primary internal SSD only.</li> </ul> </li> <li>Games can sometimes default to 800p resolution<ul> <li>Manually change the resolution per game in the <code>Steam Settings &gt; Properties &gt; Game Resolution</code> to either <code>Native</code> or other higher resolutions.</li> </ul> </li> <li>Gyro is non-functional.</li> <li>Back buttons may need to be manually remapped before they are usable.<ul> <li>Manually remap back buttons as described in hhd docs here<ul> <li>Watch this video if you need a visual guide.</li> </ul> </li> </ul> </li> </ul>"},{"location":"Handheld_and_HTPC_edition/Handheld_Wiki/GPD_Handhelds/#external-resource_1","title":"External Resource","text":"<p>For more information, check out the GPD Win Tips and Tricks guide which includes useful scripts for this handheld.</p>"},{"location":"Handheld_and_HTPC_edition/Handheld_Wiki/Lenovo_Legion_Go/","title":"Lenovo Handhelds","text":"<p>Disclaimer</p> <p>This wiki may contain outdated information.</p>"},{"location":"Handheld_and_HTPC_edition/Handheld_Wiki/Lenovo_Legion_Go/#lenovo-legion-go","title":"Lenovo Legion Go","text":""},{"location":"Handheld_and_HTPC_edition/Handheld_Wiki/Lenovo_Legion_Go/#optional-tweaks","title":"Optional Tweaks","text":"<ul> <li>Configure the HHD Overlay by opening it with Legion R</li> <li>Adjust the scaling of the UI in the Display Settings</li> </ul>"},{"location":"Handheld_and_HTPC_edition/Handheld_Wiki/Lenovo_Legion_Go/#known-issues","title":"Known Issues","text":"<ul> <li>Performance overlay might be reporting inaccurate power consumption.</li> <li>Adaptive/auto display brightness is currently broken.<ul> <li>Manual brightness slider in Steam's UI works without issues.</li> </ul> </li> <li>BIOS and controller firmware is recommended to update in Windows.</li> </ul>"},{"location":"Handheld_and_HTPC_edition/Handheld_Wiki/Lenovo_Legion_Go/#bios-update-breaks-secure-boot-key","title":"BIOS update breaks Secure Boot key","text":"<p>Read our Secure Boot guide to re-enroll the key after a BIOS update if you keep Secure Boot enabled, which is the default for this device.</p> <p>Info</p> <p>As of July 2025, external monitors are working just fine. The external display can be set to its respective native resolution and refresh rate.</p> <p></p> <p>Without additional fixes, the internal display only offers its native resolution with the correct aspect ratio. Other resolutions can be chosen, but most of the screen will remain empty.</p> <p> </p> <p>If your screen doesn't display the correct output or looks grainy, noisy, or oddly colorful then you will have to enter a TTY session and enter this command:</p> <pre><code>rm ~/.config/kwin*\n</code></pre> <p>Alternatively, ssh into it and enter this command:</p> <pre><code>mv ~/.config/kwinoutputconfig.json ~/.config/kwinoutputconfig.json.old\n</code></pre>"},{"location":"Handheld_and_HTPC_edition/Handheld_Wiki/Lenovo_Legion_Go/#external-resource","title":"External Resource","text":"<p>For more information, check out the Legion Go Tips and Tricks guide which includes useful scripts for this handheld.</p>"},{"location":"Handheld_and_HTPC_edition/Handheld_Wiki/OneXPlayer_Handhelds/","title":"OneXPlayer Handhelds","text":"<p>Disclaimer</p> <p>This wiki may contain outdated information.</p>"},{"location":"Handheld_and_HTPC_edition/Handheld_Wiki/OneXPlayer_Handhelds/#onexplayer-x1","title":"OneXPlayer X1","text":""},{"location":"Handheld_and_HTPC_edition/Handheld_Wiki/OneXPlayer_Handhelds/#known-issues","title":"Known Issues","text":"<ul> <li>Adjusting the vibration intensity is not supported yet</li> </ul>"},{"location":"Handheld_and_HTPC_edition/Handheld_Wiki/Other_Handhelds/","title":"Other Handhelds","text":""},{"location":"Handheld_and_HTPC_edition/Handheld_Wiki/Other_Handhelds/#untested-handhelds","title":"Untested Handhelds","text":"<p>Note</p> <p>Certain handhelds have been confirmed to boot Bazzite, but are plagued by missing driver support for Linux including missing audio drivers.</p> <p>Untested handhelds could work with Bazzite, but there may be major issues encountered that are undocumented.  Your mileage may vary with untested hardware. </p> <p>Bazzite does not have the required setup for other handhelds, so setup will be manually done by the end-user for different functionality if it even works properly on the unsupported device.</p>"},{"location":"Handheld_and_HTPC_edition/Handheld_Wiki/Other_Handhelds/#hhd-setup-if-not-enabled-by-default-on-device","title":"HHD Setup (If Not Enabled By Default on Device)","text":"<p>Commands for functional HHD:</p> <pre><code>systemctl start hhd@yourusername\n</code></pre> <pre><code>systemctl enable hhd@yourusername\n</code></pre> <p>Important</p> <p>Replace <code>yourusername</code> with your Bazzite username.</p>"},{"location":"Handheld_and_HTPC_edition/Handheld_Wiki/Steam_Deck/","title":"Steam Deck","text":""},{"location":"Handheld_and_HTPC_edition/Handheld_Wiki/Steam_Deck/#steam-deck-lcd-oled-models","title":"Steam Deck (LCD &amp; OLED Models)","text":""},{"location":"Handheld_and_HTPC_edition/Handheld_Wiki/Steam_Deck/#bios-updates","title":"BIOS Updates","text":"<p>It is recommended to enter <code>ujust enable-deck-bios-firmware-updates</code> in the terminal to receive Steam Deck BIOS updates.</p>"},{"location":"Handheld_and_HTPC_edition/Handheld_Wiki/Steam_Deck/#why-bazzite-over-steamos","title":"Why Bazzite over SteamOS?","text":"<p>Both SteamOS and Bazzite use Steam Gaming Mode and share packages between each other, but what about differences under the hood?  Bazzite should have most of the functionality from SteamOS with Steam Gaming Mode working as intended.</p> <ul> <li>It should function nearly identical to SteamOS.<ul> <li>The Quick Access Menu (QAM) which is accessed with the ... button on Steam Deck is functional for TDP, framerate limiting, scaling, etc. like on SteamOS.</li> <li>The same popular third-party software like Decky Loader, Emudeck, RetroDeck, etc. should install and function properly.</li> </ul> </li> <li>Reaping the benefits of Fedora Atomic Desktop:<ul> <li>Layer Fedora packages to the image without losing them between updates/reboots.</li> <li>Roll back system updates from the last 90 days.</li> <li>Alternate desktop environments available.</li> </ul> </li> <li>Bazzite includes newer versions of base packages than SteamOS which means Bazzite is always ahead of SteamOS in terms of Steam Gaming Mode and Desktop Mode features.<ul> <li>Newer package upgrades including the Linux kernel and drivers.</li> <li>Regressions may occur more often since Bazzite upgrades base packages faster than SteamOS does.</li> </ul> </li> </ul> <p>If you want to see a more in-depth comparison, read our SteamOS comparison guide.</p>"},{"location":"Handheld_and_HTPC_edition/Handheld_Wiki/Steam_Deck/#known-issues","title":"Known Issues","text":"<ul> <li>(Steam Deck OLED) The brightness is not properly restored when changing refresh rate.</li> <li>(Steam Deck OLED) MangoHUD does not report GPU clocks.</li> </ul>"},{"location":"Installing_and_Managing_Software/","title":"Installing and Managing Applications","text":"<ul> <li>Introduction to Installing Software on Bazzite</li> <li>Bazzite Portal (<code>ujust</code>)</li> <li>Bazaar App Store (<code>flatpak</code>)</li> <li>Homebrew (<code>brew</code>)</li> <li>Containers<ul> <li>Distrobox (Linux Package Managers)</li> <li>Quadlet (<code>systemd</code> and <code>podman</code> in Combination) </li> </ul> </li> <li>AppImage (Portable <code>.AppImage</code> Applications)</li> <li>Package Layering (<code>rpm-ostree</code>)</li> <li>Waydroid Setup Guide (Android Applications)</li> <li>Updates, Rollbacks, and Rebasing Images<ul> <li>Updates</li> <li>Rolling Back Updates</li> <li>Rebasing Images</li> <li><code>bazzite-rollback-helper</code></li> </ul> </li> </ul>"},{"location":"Installing_and_Managing_Software/AppImage/","title":"AppImage","text":"<p>AppImage is a universal package format that attempts to bundle dependencies that an application requires into one portable file. They can be installed by downloading any file with a <code>.AppImage</code> file extension and then giving it executable permissions in the file's properties so the application can run properly. Like Windows executable files, they are usually found on the project's website to download. You should only download AppImages from sources that you trust.</p>"},{"location":"Installing_and_Managing_Software/AppImage/#gear-lever","title":"Gear Lever","text":"<p>Applications installed as an AppImage can integrate with your desktop and be managed with Gear Lever which you can install in Bazaar.  Gear Lever will also check for new updates, but upgrades will still need to be applied manually. It is highly recommended to install Gear Lever to manage AppImages.</p>"},{"location":"Installing_and_Managing_Software/AppImage/#project-website","title":"Project Website","text":"<p>https://appimage.org/</p>"},{"location":"Installing_and_Managing_Software/Containers/","title":"Containers","text":""},{"location":"Installing_and_Managing_Software/Containers/#what-are-containers","title":"What are containers?","text":"<p>Containers are isolated environments for software to run.  Bazzite utilizes containers in a software context for applications that either run better in a container environment or are not available in the Bazaar app store.</p>"},{"location":"Installing_and_Managing_Software/Containers/#distrobox","title":"Distrobox","text":"<p>Distrobox allows users to run other minimal versions Linux operating systems within their own containerized environment with access to their own repositories.  Real world examples include applications that only have Linux support for Ubuntu and ship a <code>.deb</code> file on their website.  An Ubuntu container can be created with DistroShelf and then the <code>.deb</code> file can be installed within the container and exported so it appears in your applications.</p> <p>Quadlet is specifically used for running services like media servers, game servers, etc.  Quadlet is advanced in comparison to other package formats and relies heavily on system-level tooling that is pre-installed on Bazzite. There is no <code>quadlet</code> command and requires declaratively creating services with it using systemd units and Podman.</p>"},{"location":"Installing_and_Managing_Software/Distrobox/","title":"Distrobox Containers","text":""},{"location":"Installing_and_Managing_Software/Distrobox/#basic-usage","title":"Basic Usage","text":"<p>Run other minimal variants of popular Linux distributions in Bazzite inside of a container and access each distribution's packages without any of their dependencies and libraries affecting the host machine.</p> <ul> <li>Containers are not virtual machines.</li> <li>Containers are intended to be disposable and may run into issues where they need to be recreated.</li> <li>Using this method to obtain software requires knowledge of how traditional Linux operating systems install packages.<ul> <li>Create a test container to familiarize yourself with basic Linux commands before diving in further.</li> </ul> </li> </ul> <p>Distrobox containers run sub-systems of other popular Linux distributions with access to their package managers (<code>apt</code>, <code>dnf</code>, <code>pacman</code>, etc.) and their package formats (<code>.deb</code>/<code>.rpm</code>) and any additional repositories like the AUR. Distrobox containers can be used for both development environments and installing applications that are not available in any of the other installation methods which can be exclusive to specific package managers.</p>"},{"location":"Installing_and_Managing_Software/Distrobox/#linux-distribution-examples","title":"Linux Distribution Examples:","text":"OS Package Manager Search for Packages Fedora <code>dnf</code> Fedora Packages / COPR Packages Arch <code>pacman</code> Arch Linux Packages / AUR Packages Debian / Ubuntu <code>apt</code> Debian Packages / Ubuntu Packages (PPA) openSUSE <code>zypper</code> openSUSE Packages Void <code>xbps</code> Void Linux Packages Alpine <code>apk</code> Alpine Linux Packages"},{"location":"Installing_and_Managing_Software/Distrobox/#arch-linux-distrobox-container-example","title":"Arch Linux Distrobox Container Example:","text":"<p>I use Arch (in a container) btw.</p>"},{"location":"Installing_and_Managing_Software/Distrobox/#use-cases","title":"Use Cases","text":"<p>Distrobox containers can be used for both development environments and installing applications that are not available in any of the other installation methods which can be exclusive to specific package managers.</p>"},{"location":"Installing_and_Managing_Software/Distrobox/#distrobox-graphical-interface","title":"Distrobox Graphical Interface","text":"<p>Distrobox containers can be created and managed graphically with DistroShelf which is pre-installed.</p>"},{"location":"Installing_and_Managing_Software/Distrobox/#desktop-integration","title":"Desktop Integration","text":"<p>Applications with a graphical user interface can integrate with your system with an application shortcut by exporting the application using the below command in the container terminal window:</p> <p><pre><code>distrobox-export --app &lt;package&gt;\n</code></pre> To \"un-export\" the app, enter the command below in the container terminal window:</p> <pre><code>distrobox-export --delete --app &lt;package&gt;\n</code></pre>"},{"location":"Installing_and_Managing_Software/Distrobox/#manually-create-pre-configured-distrobox-containers","title":"Manually Create Pre-Configured Distrobox Containers","text":"<pre><code>ujust distrobox-assemble\n</code></pre> <p>Select the container that you want to use.</p> <p>Advanced users: Declare your own custom Distrobox containers following the <code>distrobox-assemble</code> documentation.</p>"},{"location":"Installing_and_Managing_Software/Distrobox/#entering-the-container","title":"Entering The Container","text":"<p>Swap between different containers in your host with the terminal or alternatively enter:</p> <pre><code>distrobox enter &lt;container&gt;\n</code></pre>"},{"location":"Installing_and_Managing_Software/Distrobox/#removing-distrobox-containers","title":"Removing Distrobox Containers","text":"<p>Delete containers graphically with DistroShelf.</p> <p>Alternatively, use the command line:</p> <pre><code>distrobox stop &lt;container_name&gt;\n</code></pre> <pre><code>distrobox rm -f &lt;container_name&gt;\n</code></pre>"},{"location":"Installing_and_Managing_Software/Distrobox/#distrobox-video-guide","title":"Distrobox Video Guide","text":""},{"location":"Installing_and_Managing_Software/Distrobox/#project-website","title":"Project Website","text":"<p>https://distrobox.it/</p>"},{"location":"Installing_and_Managing_Software/Flatpak/","title":"Bazaar App Store","text":""},{"location":"Installing_and_Managing_Software/Flatpak/#purpose","title":"Purpose","text":"<p>Bazaar is the primary method of installing applications on Bazzite (outside of the small selection of software available in the Bazzite Portal or as a <code>ujust</code> command)  and is recommended to install most applications from Bazaar over other formats for most software when possible.  Bazaar is a frontend for Flatpaks that are from Flathub.</p>"},{"location":"Installing_and_Managing_Software/Flatpak/#what-is-flatpak","title":"What is Flatpak?","text":"<p>Flatpak is a universal containerized package format that tries to sandbox applications through flexible permissions that the application has access to on your system.  It is the primary method of installing applications on Bazzite and the most recommended way to install software over other formats outside of the few exceptions of software available in the Bazzite Portal which take priority. Flatpaks can be graphically installed, upgraded, and uninstalled via the Bazaar app store.</p>"},{"location":"Installing_and_Managing_Software/Flatpak/#terminal-installation","title":"Terminal Installation","text":"<p>Alternatively open a host terminal and enter:</p> <pre><code>flatpak install &lt;application&gt;\n</code></pre>"},{"location":"Installing_and_Managing_Software/Flatpak/#manage-flatpaks","title":"Manage Flatpaks","text":"<p>Manage Flatpaks with Flatseal and Warehouse which are both pre-installed.</p>"},{"location":"Installing_and_Managing_Software/Flatpak/#flatseal","title":"Flatseal","text":"<p>Flatseal is for changing application permissions if necessary.</p> <p>Sometimes a project's website or Github repository contain information on what permissions need to be changed to perform certain functionality.</p>"},{"location":"Installing_and_Managing_Software/Flatpak/#warehouse","title":"Warehouse","text":"<p>Warehouse is a utility that gives users a graphical interface to downgrade applications, install remote Flatpak sources outside of Flathub at your own risk, and backup application user data.</p>"},{"location":"Installing_and_Managing_Software/Flatpak/#project-website","title":"Project Website","text":"<p>https://github.com/kolunmi/bazaar</p>"},{"location":"Installing_and_Managing_Software/Homebrew/","title":"Homebrew","text":""},{"location":"Installing_and_Managing_Software/Homebrew/#what-is-homebrew","title":"What is Homebrew?","text":"<p>Note</p> <p>Any package that requires root privileges will either need a rootful Distrobox container or has to be layered with <code>rpm-ostree</code>.</p> <p>Homebrew is a package manager that installs packages into their own prefix. It is primarily used for command-line interface (CLI) and terminal user interface (TUI) applications. Homebrew can also install graphical applications using the <code>--cask</code> flag, but most are for macOS as support for casks on Linux is still developing. Use the Bold Brew application or the terminal using the command below to install packages.</p> <p>Install packages in a host terminal with this terminal command:</p> <pre><code>brew install &lt;package&gt;\n</code></pre>"},{"location":"Installing_and_Managing_Software/Homebrew/#bold-brew","title":"Bold Brew","text":"<p>The Bold Brew application offers a terminal user interface (TUI) for installing common Homebrew packages.</p>"},{"location":"Installing_and_Managing_Software/Homebrew/#project-website","title":"Project Website","text":"<p>https://brew.sh/</p>"},{"location":"Installing_and_Managing_Software/Quadlet/","title":"Quadlet (Services)","text":""},{"location":"Installing_and_Managing_Software/Quadlet/#quadlet-usecases","title":"Quadlet Usecases","text":"<p>Quadlet is a feature of podman that allows a user to run a container as systemd units. It works by using a declarative syntax like docker compose but integrates to systemd and uses podman as a backend.</p> <p>Quadlet can be used for application packaged as a container such as a server application. You can find a lot of examples of containerized applications from Linux Server.</p>"},{"location":"Installing_and_Managing_Software/Quadlet/#managing-quadlet","title":"Managing Quadlet","text":"<p>Quadlet can be managed like any other systemd service using below command.</p> <p>Checking Quadlet status <pre><code>systemctl --user status &lt;service&gt;\n</code></pre></p> <p>Stopping Quadlet <pre><code>systemctl --user stop &lt;service&gt;\n</code></pre></p> <p>You can see more commands in man systemctl or tldr systemctl.</p> <p>Note</p> <p>Do not add the <code>.container</code> suffix when you interact with systemctl or an error will occur.</p>"},{"location":"Installing_and_Managing_Software/Quadlet/#quadlet-file-locations","title":"Quadlet File Locations","text":"<p>You can put your quadlet in these locations sorted by priority:</p> <ul> <li><code>$XDG_RUNTIME_DIR/containers/systemd/</code> - Usually used for temporary quadlet</li> <li><code>~/.config/containers/systemd/</code> - Recommended location</li> <li><code>/etc/containers/systemd/users/$(UID)</code></li> <li><code>/etc/containers/systemd/users/</code></li> </ul> <p>Note</p> <p>If you want your service to start even when you are not logged in, run <code>loginctl enable-linger $USER</code> to start it automatically.</p>"},{"location":"Installing_and_Managing_Software/Quadlet/#running-quadlet-on-startup","title":"Running Quadlet on Startup","text":"<p>You may want to run your quadlet automatically on startup, just add an install section to the quadlet file if you want it to autostart. Most of the time <code>default.target</code> is what you want but if you need other target you can read about that on systemd docs.</p> <pre><code>[Install]\nWantedBy=default.target\n</code></pre>"},{"location":"Installing_and_Managing_Software/Quadlet/#converting-docker-compose-to-quadlet-unit","title":"Converting Docker Compose to Quadlet Unit","text":"<p>You will find that most of containerized apps in the web are built using docker compose. Even the Linux Server that is linked above has all containers documented using a compose file. So you will need to convert it first, before running it as quadlet, fortunately you can use podlet to help you converting it.</p> <p>Note</p> <p>By default quadlet require full repository name. Most images are in docker hub so add <code>docker.io/</code> (e.g \"nginxinc/nginx-unprivileged\" becomes \"docker.io/nginxinc/nginx-unprivileged\") to it.</p>"},{"location":"Installing_and_Managing_Software/Quadlet/#running-rootful-container-as-quadlet","title":"Running Rootful Container as Quadlet","text":"<p>While ideally you would run all containers using rootless podman, unfortunately not all containers will work with it.  Use rootful podman by using a different quadlet path and run using root systemctl (without <code>--user</code>).</p> <p>Rootful Quadlet Paths - <code>/run/containers/systemd/</code> - Temporary quadlet - <code>/etc/containers/systemd/</code> - Recommended location - <code>/usr/share/containers/systemd/</code> - Image defined</p>"},{"location":"Installing_and_Managing_Software/Quadlet/#common-quadlet-key-description","title":"Common Quadlet Key Description","text":"Option Example Description ContainerName ContainerName=nginx Name of the container. Image Image=docker.io/nginxinc/nginx-unprivileged Container image that you want to use. AutoUpdate AutoUpdate=registry Source to check for update. The value is either <code>registry</code> or <code>local</code>. PublishPort PublishPort=8080:8080 Port opened by container. (HOST_PORT:CONTAINER_PORT) Volume Volume=/path/to/data:/data:z Link host folder with container folder. (HOST_FOLDER:CONTAINER_FOLDER:OPTION) Network Network=host Network used by container. The value can be <code>host</code>, <code>none</code>, or user defined network name <p>Note</p> <p>The <code>z</code> option in volume is to prevent selinux from blocking access to the folder. You can read more here.</p>"},{"location":"Installing_and_Managing_Software/Quadlet/#troubleshooting","title":"Troubleshooting","text":"<p>If your quadlet for some reason isn't found or starting, you can debug the container unit using <code>/usr/libexec/podman/quadlet -dryrun</code> for system quadlet or <code>/usr/libexec/podman/quadlet -user -dryrun</code> for user quadlet.</p>"},{"location":"Installing_and_Managing_Software/Quadlet/#examples","title":"Examples","text":"<p>Real world examples for Quadlet usage.</p>"},{"location":"Installing_and_Managing_Software/Quadlet/#minecraft-server-hosting","title":"Minecraft Server Hosting","text":"<p>Note</p> <p>Don't forget to run <code>systemctl --user daemon-reload</code> after creating the file</p> <p>Documentation: https://docker-minecraft-server.readthedocs.io/en/latest Quadlet File: <pre><code># ~/.config/containers/systemd/minecraft.container\n[Container]\nContainerName=minecraft\nEnvironment=EULA=TRUE\nImage=docker.io/itzg/minecraft-server\nAutoUpdate=registry\nPublishPort=25565:25565\nVolume=/path/to/data:/data:z\n\n# Remove if you don't want autostart\n[Install]\nWantedBy=default.target\n</code></pre></p> <p>Note</p> <p>Use absolute path for volume, e.g <code>/home/username/minecraft/data</code>.</p>"},{"location":"Installing_and_Managing_Software/Quadlet/#nginx-web-server","title":"NGINX Web Server","text":"<p>Create a file called <code>~/.config/containers/systemd/nginx.container</code> with content below. <pre><code>[Container]\nContainerName=nginx\nImage=docker.io/nginxinc/nginx-unprivileged\nAutoUpdate=registry\nPublishPort=8080:8080\n</code></pre></p> <p>Save it and run the code below.</p> <pre><code>systemctl --user daemon-reload\nsystemctl --user start nginx\nxdg-open localhost:8080\n</code></pre>"},{"location":"Installing_and_Managing_Software/Quadlet/#plex-media-server","title":"Plex Media Server","text":"<p>Documentation: https://github.com/plexinc/pms-docker Quadlet File: <pre><code># ~/.config/containers/systemd/plex.container\n[Container]\nContainerName=plex\nEnvironment=TZ=Your/TimeZone\nImage=docker.io/plexinc/pms-docker\nAutoUpdate=registry\nNetwork=host\nVolume=/path/to/config:/config:z\nVolume=/path/to/transcode:/transcode:z\nVolume=/path/to/media:/data:z\n\n# Remove if you don't want autostart\n[Install]\nWantedBy=default.target\n</code></pre></p> <p>Note</p> <p>You can find list of timezones here.</p> <p>Note</p> <p>Use absolute path for volume, e.g <code>/home/username/plex/config</code>.</p> <p>Note</p> <p>You can mount multiple volumes for your media, e.g <code>Volume=/path/to/media:/tv:z</code> and <code>Volume=/path/to/another/media:/movie:z</code>. Consult the documentation for more info.</p>"},{"location":"Installing_and_Managing_Software/Quadlet/#video-tutorial","title":"Video Tutorial","text":""},{"location":"Installing_and_Managing_Software/Quadlet/#samba-server","title":"Samba Server","text":"<p>Documentation: https://github.com/ServerContainers/samba Quadlet File: <pre><code># /etc/containers/systemd/samba.container\n[Container]\nEnvironment=ACCOUNT_username=password\n# Protected share with write access\nEnvironment=\"SAMBA_VOLUME_CONFIG_protected=[My Share]; path=/shares/protected; valid users = username; guest ok = no; read only = no; browseable = yes\"\n# Open share with readonly access\nEnvironment=\"SAMBA_VOLUME_CONFIG_guest=[Guest Share]; path=/shares/guest; guest ok = yes; browseable = yes\"\nImage=ghcr.io/servercontainers/samba:smbd-only-latest\nAutoUpdate=registry\nNetwork=host\nVolume=/path/to/protected:/shares/protected:z\nVolume=/path/to/guest:/shares/guest:z\n\n# Remove if you don't want autostart\n[Install]\nWantedBy=default.target\n</code></pre></p> <p>Note</p> <p>You can find list of timezone here.</p> <p>Note</p> <p>Use absolute path for volume, e.g <code>/home/username/samba/guest</code>.</p>"},{"location":"Installing_and_Managing_Software/Quadlet/#useful-links","title":"Useful Links","text":"<ul> <li>https://podman.io/</li> <li>https://docs.podman.io/en/stable/markdown/podman-systemd.unit.5.html</li> <li>https://www.redhat.com/en/blog/quadlet-podman</li> </ul>"},{"location":"Installing_and_Managing_Software/Waydroid_Setup_Guide/","title":"Waydroid Setup Guide","text":""},{"location":"Installing_and_Managing_Software/Waydroid_Setup_Guide/#what-is-waydroid","title":"What is Waydroid?","text":"<p>Attention</p> <p>Waydroid does not work on Nvidia hardware.</p> <p></p> <p>Waydroid is an Android container that runs on Linux. Bazzite users can run Android applications using this method.</p>"},{"location":"Installing_and_Managing_Software/Waydroid_Setup_Guide/#first-time-setup","title":"First Time Setup","text":"<p>Open a host terminal and enter this command to setup Waydroid:</p> <pre><code>ujust setup-waydroid\n</code></pre>"},{"location":"Installing_and_Managing_Software/Waydroid_Setup_Guide/#initialize-waydroid","title":"Initialize Waydroid","text":"<p>Waydroid requires users to initialize it for the first time which can be done by selecting: <code>Initialize Waydroid</code></p> <p>Make sure this worked by entering this command:</p> <pre><code>/usr/bin/waydroid-launcher\n</code></pre> <p>This will launch Waydroid for the first time.</p>"},{"location":"Installing_and_Managing_Software/Waydroid_Setup_Guide/#configure-waydroid","title":"Configure Waydroid","text":"<p>Customize your Waydroid container</p>"},{"location":"Installing_and_Managing_Software/Waydroid_Setup_Guide/#part-1-stop-waydroid-session","title":"Part 1: Stop Waydroid Session","text":"<p>Waydroid needs to stop running to configure properly.</p> <p>Open a host terminal and enter this command:</p> <pre><code>waydroid session stop\n</code></pre>"},{"location":"Installing_and_Managing_Software/Waydroid_Setup_Guide/#part-2-configuration","title":"Part 2: Configuration","text":"<p>Open a host terminal and enter this command:</p> <pre><code>ujust setup-waydroid\n</code></pre> <p>Selecting <code>Configure Waydroid</code> will allow users to install additional Android tweaks with the Waydroid Extras Scripts.</p> <ol> <li>Select Android version you have installed. To find installed Android version, start Waydroid, open Settings app then go to \"About This Phone\". Your Android version will be 11 or 13.</li> <li>Select items to install</li> </ol>"},{"location":"Installing_and_Managing_Software/Waydroid_Setup_Guide/#available-waydroid-extras","title":"Available Waydroid Extras:","text":"<ul> <li>GApps (Default Android applications including the Google Play Store) or microG (Free alternatives to Google applications)</li> </ul> <ul> <li>ARM Translation (libndk or libhoudini)</li> <li>libhoudini offers better overall compatibility compared to libndk.     - Some games may run on only one of libhoudini or libndk.  On Android 11, libhoudini will run significantly slower than libndk if you have AMD CPU.     - Do not install both of them at the same time. If you need to switch, uninstall your current translation layer before installing a new one.</li> </ul> <ul> <li>Magisk (Android power user suite)</li> </ul> <ul> <li>Logitech Smartdock Support (SmartDock hardware support)</li> </ul> <ul> <li>F-Droid Privileged Extension (Proper F-Droid support)</li> </ul> <ul> <li><code>widevine</code> (Support for video streaming DRM)</li> </ul>"},{"location":"Installing_and_Managing_Software/Waydroid_Setup_Guide/#get-google-device-id-to-get-certified-gapps","title":"Get Google Device ID to Get Certified (GApps)","text":"<ol> <li> <p>Launch Waydroid    (Waydroid must be running)</p> </li> <li> <p>After selecting your current Android version, select <code>Get Google Device ID to Get Certified</code> especially if you plan to use the Google Play Store (GApps).</p> </li> <li> <p>Follow the instructions in the terminal output.</p> </li> </ol> <p>After verification has happened, it will usually take a while before your device is Google Play certified.</p>"},{"location":"Installing_and_Managing_Software/Waydroid_Setup_Guide/#add-as-a-non-steam-shortcut","title":"Add as a Non-Steam Shortcut","text":"<p>This is useful for Bazzite images that use Steam Gaming Mode.</p> <p>Make sure to add <code>/usr/bin/waydroid-launcher</code> to Steam as a non-Steam game for Waydroid to work properly in Steam Gaming Mode.</p> <p></p>"},{"location":"Installing_and_Managing_Software/Waydroid_Setup_Guide/#enable-multi-touch-support","title":"Enable Multi-Touch Support","text":"<p>To use multi-touch gestures in Waydroid while running under Steam Gaming Mode, you need to enable \"Touchscreen Native Support\" in Steam's controller settings:</p> <ol> <li>Within your Waydroid shortcut, go to Controller Settings.</li> <li>Go to Edit Layout &gt; Action Sets &gt; Default.</li> <li>Select Add Always-On command.</li> <li>Under System, select the Touchscreen Native Support command.</li> </ol> <p></p>"},{"location":"Installing_and_Managing_Software/Waydroid_Setup_Guide/#waydroid-tips-tricks","title":"Waydroid Tips &amp; Tricks","text":"<p>This section is dedicated to more specific operations and issues within Waydroid running on Bazzite.</p>"},{"location":"Installing_and_Managing_Software/Waydroid_Setup_Guide/#waydroid-helper-application","title":"Waydroid Helper application","text":"<p>waydroid-helper is a GUI app that enables more advanced configuration and control over your waydroid installations.</p> <p>To install it, run the following <code>ujust</code> command:</p> <pre><code>ujust setup-waydroid helper\n</code></pre> <p>You can alternatively go directly to their releases and install the latest AppImage via GearLever.</p>"},{"location":"Installing_and_Managing_Software/Waydroid_Setup_Guide/#disable-inputs-to-waydroid-when-unfocused","title":"Disable Inputs to Waydroid When Unfocused","text":"<p>Waydroid has an issue where it will register inputs from controllers, keyboards, and other input devices even when the window is not focused.</p> <p>Disable this functionality:</p> <p>Note</p> <p>Waydroid must be running!</p> <p>In a host terminal, run this command:</p> <pre><code>waydroid prop set persist.waydroid.uevent false\n</code></pre> <p>If you ever want to undo this change, run the same steps but set <code>true</code> instead of <code>false</code> with the same command.</p>"},{"location":"Installing_and_Managing_Software/Waydroid_Setup_Guide/#mouse-clicks-to-touch-input","title":"Mouse Clicks to Touch Input","text":"<p>Some applications do not expect mouse clicks and only respond to touchscreen taps.</p> <p>Note</p> <p>Waydroid must be running!</p> <p>You can use this command in a host terminal to enable this per-application:</p> <pre><code>waydroid prop set persist.waydroid.fake_touch \"PACKAGE_NAME_HERE\"\n</code></pre> <p>Note</p> <p>Package names are usually in the format of \"com.example.appname\". You can find the package name for the application at the bottom of the \"App info\" page in the Settings app.</p> <p>Wildcards are also supported, so \"com.rovio.*\" would apply to all games by Rovio.</p> <p>An example for the app \"Fate/Grand Order\" would be: <code>waydroid prop set persist.waydroid.fake_touch \"com.aniplex.fategrandorder.en\"</code></p> <p>The application inside of Waydroid needs to be restarted for the changes to take effect.</p> <p>Warning</p> <p>Only set specific applications with this command! Setting this globally to the system using a wildcard can cause irregular behavior with the mouse cursor.</p> <p>To revert these changes, use the following command in a host terminal:</p> <pre><code>waydroid prop set persist.waydroid.fake_touch \"\"\n</code></pre>"},{"location":"Installing_and_Managing_Software/Waydroid_Setup_Guide/#resolution-density-options","title":"Resolution &amp; Density Options","text":"<p>This is intended for users who have issues with Waydroid's resolution, scaling, or running Waydroid nested. This is optional.</p> <p>Open a host terminal and enter the following commands:</p> <pre><code>sudoedit /etc/default/waydroid-launcher\n</code></pre> <pre><code>sudoedit /etc/default/steamos-nested-desktop\n</code></pre> <p>Save the text files when done.</p>"},{"location":"Installing_and_Managing_Software/Waydroid_Setup_Guide/#waydroid-hybrid-graphics-fix","title":"Waydroid Hybrid Graphics Fix","text":"<p>This is only intended for users who have multiple GPUs in their hardware who experience graphical corruptions in Waydroid.</p> <p>Enter in a host terminal:</p> <pre><code>ujust setup-waydroid\n</code></pre> <p>Then <code>Select GPU for Waydroid</code> which will give the option on what GPU to utilize for Waydroid to fix graphical corruptions.</p>"},{"location":"Installing_and_Managing_Software/Waydroid_Setup_Guide/#reset-waydroid","title":"Reset Waydroid","text":"<p>Warning</p> <p>You will lose all of your Waydroid data.</p> <p>If you experience issues or want a fresh Waydroid container, then select <code>Reset Waydroid</code> after entering:</p> <pre><code>ujust setup-waydroid\n</code></pre>"},{"location":"Installing_and_Managing_Software/rpm-ostree/","title":"Package Layering","text":""},{"location":"Installing_and_Managing_Software/rpm-ostree/#using-rpm-ostree","title":"Using <code>rpm-ostree</code>","text":"<p>Attention</p> <p>Layering packages irresponsibly can be destructive and may prevent updates as well as other issues until the layered packages are removed.</p> <p>Install Fedora Linux packages on top of the existing Bazzite image by using the <code>rpm-ostree</code> terminal command.  Use for packages that cannot be installed from Homebrew or ran inside of a container.  Layered packages can break system upgrades until removed due to dependency issues since the package will have to be updated with the rest of the image.  It also causes upgrades to take longer to run.</p>"},{"location":"Installing_and_Managing_Software/rpm-ostree/#key-notes","title":"Key Notes","text":"<ul> <li>Layering packages will require a system reboot when it finishes creating the new deployment with the package(s) added to your image.</li> <li>Use this method as a last resort and for anything at a \"system-level\" only since it can pause updates, if the package contains dependency issues with future upgrades, until the package is uninstalled.</li> </ul>"},{"location":"Installing_and_Managing_Software/rpm-ostree/#terminal-commands-related-to-package-layering","title":"Terminal Commands Related to Package Layering","text":"<p>Use these commands at your own risk.</p>"},{"location":"Installing_and_Managing_Software/rpm-ostree/#layer-packages","title":"Layer Package(s)","text":"<pre><code>rpm-ostree install &lt;package&gt;\n</code></pre> <p>Installs Fedora package(s) to the system that stay between updates, reboot to apply the installation.</p>"},{"location":"Installing_and_Managing_Software/rpm-ostree/#uninstall-layered-packages","title":"Uninstall Layered Package(s)","text":"<pre><code>rpm-ostree uninstall &lt;package&gt;\n</code></pre> <p>Uninstalls any layered packages added to the system, reboot to apply the uninstallation.</p>"},{"location":"Installing_and_Managing_Software/rpm-ostree/#search-for-a-package","title":"Search for a Package","text":"<pre><code>rpm-ostree search &lt;package&gt;\n</code></pre> <p>Searches for Fedora packages that can be installed.</p>"},{"location":"Installing_and_Managing_Software/rpm-ostree/#view-currently-layered-packages","title":"View Currently Layered Packages","text":"<pre><code>rpm-ostree status\n</code></pre> <p>This will output the layered packages in your Bazzite installation.</p>"},{"location":"Installing_and_Managing_Software/rpm-ostree/#installing-rpm-files","title":"Installing RPM Files","text":"<p>Fedora Distrobox containers should be used for most <code>.rpm</code> files, but sometimes they need to be installed to your host if it isn't working well with a container.</p> <p>You can install RPM binaries to your host with <code>rpm-ostree</code> by entering:</p> <pre><code>rpm-ostree install &lt;package&gt;.rpm\n</code></pre> <p>You may need to copy the full path (<code>/path/to/rpmfile.rpm</code>) for it to install properly.</p> <p>Important</p> <p>The downside of installing local RPM files outside of the Fedora repositories is updates for the specific RPM package will not apply automatically.</p>"},{"location":"Installing_and_Managing_Software/rpm-ostree/#how-do-i-addremove-copr-repositories","title":"How do I add/remove COPR repositories?","text":"<p>Warning</p> <p>It is highly advised to not use third-party COPR repos if possible, so be aware there are risks associated with it including broken updates until removed.</p> Enable COPRDisable COPR DNF5 (Fedora COPR)DNF5 (repo file)Manually <pre><code>sudo dnf5 copr enable &lt;USER&gt;/&lt;PROJECT&gt;\n</code></pre> <p>This method works with COPR other than Fedora's (ex.: Docker)</p> <pre><code>sudo dnf5 config-manager addrepo --from-repofile=https://url/to/file.repo\n</code></pre> <ol> <li> <p>Download the .repo file and save it to <code>/etc/yum.repos.d/</code></p> </li> <li> <p>Then install the package(s) with <code>rpm-ostree</code></p> </li> <li> <p>Reboot</p> </li> </ol> <p>If you experience issues updating your system due to GPG signature issues, then this can be fixed by either removing the COPR repository, or editing the file by changing <code>gpgcheck=1</code> to <code>gpgcheck=0</code> (or similar) and saving it at your own risk.</p> <p>Ensure to remove any package installed with the COPR beforehand.</p> DNF5 (Fedora COPR)DNF5 (repo file)Manually <pre><code>sudo dnf5 copr disable &lt;USER&gt;/&lt;PROJECT&gt;\n</code></pre> <p>Remove the <code>.repo</code> at <code>/etc/yum.repos.d/</code></p> <p>Remove the <code>.repo</code> at <code>/etc/yum.repos.d/</code></p>"},{"location":"Installing_and_Managing_Software/rpm-ostree/#how-to-restore-default-coprs","title":"How to restore default COPRs","text":"<pre><code># Remove all current repos\nsudo rm /etc/yum.repos.d/*\n\n# Now copy the default repo files fro /usr/etc to /etc\nsudo cp /usr/etc/yum.repos.d/* /etc/yum.repos.d/\n</code></pre>"},{"location":"Installing_and_Managing_Software/rpm-ostree/#major-caveats-using-rpm-ostree","title":"MAJOR caveats using <code>rpm-ostree</code>","text":"<p>Layering packages can cause severe consequences including:</p> <ul> <li>Pause system updates until package(s) are uninstalled.</li> <li>Prevent rebasing to different images until package(s) are uninstalled.</li> <li>Conflict with existing packages as part of the image leading to dependency issues.</li> <li>Updates taking longer to download as you layer more packages to your system.</li> </ul> <p>Layering packages are mostly intended for system-level applications, libraries, and other dependencies. It is recommended to use Flatpak, Homebrew, containers, AppImage, Waydroid, or running the Windows version through a compatibility layer before installing software with <code>rpm-ostree</code>.  Layering packages for a temporary time period is the better alternative than keeping a package layered indefinitely.</p>"},{"location":"Installing_and_Managing_Software/rpm-ostree/#how-to-remove-all-layered-packages","title":"How to remove ALL layered packages","text":"<p>If you run into issues upgrading due to a layered package conflict, then either optionally uninstall the conflicted package(s) or remove all layered packages with this command:</p> <pre><code>rpm-ostree reset\n</code></pre>"},{"location":"Installing_and_Managing_Software/rpm-ostree/#project-website","title":"Project Website","text":"<p>https://coreos.github.io/rpm-ostree/</p>"},{"location":"Installing_and_Managing_Software/software-intro/","title":"Introduction to Installing Software on Bazzite","text":""},{"location":"Installing_and_Managing_Software/software-intro/#linux-package-formats","title":"Linux Package Formats","text":"<p>Package formats ranked from most recommended to least recommended for daily usage:</p> <ol> <li>Bazzite Portal (<code>ujust</code> Commands) (Convenience Commands) - Custom scripts maintained by Bazzite &amp; Universal Blue contributors that can also install a small subset of applications. (This takes precedent over other formats but since it can only install only a small set of software, it is considered as an extension to system-level settings as opposed to an app store.)</li> <li>Bazaar App Store (Flatpak) (Graphical Applications) - Universal package format using a permissions-based model and should be used for most graphical applications, it is primary method of obtaining software on Bazzite.</li> <li>Homebrew (Command-Line Tools) - Install applications intended to run inside of the terminal (CLI/TUI).</li> <li>Containers - Run applications in an isolated environment to avoid dependency issues.     4a. Distrobox Containers (Linux Packages &amp; Development Workflows) - Access to most Linux package managers for software that do not support Flatpak and Homebrew and for use as development boxes.     4b. Quadlet  (Services) - Run containerized applications as a systemd service.</li> <li>AppImage (Portable Graphical Applications) - Portable universal package format that relies on specific host libraries at a system-level, usually obtained from a project's website.</li> <li><code>rpm-ostree</code> (System-Level Packages) - Layer Fedora packages at a system-level (not recommended, use as a last resort)</li> </ol>"},{"location":"Installing_and_Managing_Software/software-intro/#non-linux-formats","title":"Non-Linux Formats","text":"<p>Bazzite can also run Windows and Android applications too.  Please note that not all software intended for Windows and Android will run on Bazzite.</p>"},{"location":"Installing_and_Managing_Software/software-intro/#windows-executables","title":"Windows Executables","text":"<p>Use a WINE front-end:</p> <ul> <li>Steam (pre-installed) has a Windows compatibility layer built-in.</li> <li>Lutris (pre-installed) for non-Steam PC games and non-gaming software.</li> <li>Faugus Launcher (Available in Bazaar) as an alternative to Lutris.</li> <li>Heroic Games Launcher (Available in Bazaar) for proper Epic Games, GOG, and Amazon Games integration.</li> <li>Greenlight (Available in Bazaar) for streaming Windows store games and Gamepass. (Streaming only)</li> <li>WineZGUI (Available in Bazaar) for less complicated Windows applications that don\u2019t require special considerations.</li> </ul> <p>Read the Bazzite Gaming Guide for more information on running Windows games on Linux.</p>"},{"location":"Installing_and_Managing_Software/software-intro/#android-apps","title":"Android Apps","text":"<p>Follow the Waydroid Setup Guide to install Android applications on Bazzite.</p>"},{"location":"Installing_and_Managing_Software/software-intro/#package-format-recommendation-scenarios","title":"Package Format Recommendation Scenarios","text":"<p>Note</p> <pre><code>Please note that only a small selection of software are available to install in the Bazzite Portal so it is not listed.\n</code></pre> <p> </p> Package Format Graphical Application (GUI) Command\u2011Line / System\u2011Level Package Bazaar App Store (Flatpak) Primary method for obtaining graphical applications. Not recommended for command\u2011line applications or utilities. Homebrew Only a few apps (e.g., VSCode via Universal Blue cask) are recommended to install graphically. Highly recommended for command\u2011line tools. Containers (Distrobox / Quadlet) If not available in Bazaar, install the generic Linux package inside a Distrobox container and export it. For services, create a Quadlet. Recommended if a Homebrew package does not exist. AppImage Find an AppImage online at your own risk from a trusted source. Use Gear Lever (available in Bazaar) for proper system integration. \u2014 Package Layering If none of the above options work, layer the package at your own risk. Layer only if no other option works. Other Some software ships as a <code>.tar.gz</code> with an executable. It may run on Bazzite after making it executable in the file properties. Alternatively, use a Wine frontend (e.g., Lutris) for Windows versions. Waydroid may work if an Android port exists. \u2014 Custom Image \u2014 Intended for alternate desktop environments or software for unusual hardware; a custom Bazzite image may be required."},{"location":"Installing_and_Managing_Software/ujust/","title":"<code>ujust</code> Commands","text":""},{"location":"Installing_and_Managing_Software/ujust/#usage","title":"Usage","text":"<p>Note</p> <p>Use the Bazzite Portal application as a graphical interface for popular <code>ujust</code> commands.</p> <p><code>ujust</code> commands that automate tasks using scripts which can be utilized to for system configuration and maintenance. It also can install specialized software that ships with Bazzite as an installation script by the maintainers and contributors of the project.  Please note that some of the software that can be installed from <code>ujust</code> commands can add layered packages to your installation which is generally not recommended.</p> <p> <sub>This will output a list of available commands.</sub></p> <p>Open a host terminal and enter this command:</p> <pre><code>ujust\n</code></pre> <p></p> <pre><code>ujust --choose\n</code></pre> <p>This will show a terminal user interface of <code>ujust</code> commands that you can choose to execute with arrow keys or mouse input.</p> <p>Attention</p> <p>Commands that require values or flags do not function with this method.</p>"},{"location":"Installing_and_Managing_Software/ujust/#manually-entering-commands","title":"Manually entering commands","text":"<p>Find the command you want to use and enter:</p> <pre><code>ujust &lt;command&gt;\n</code></pre> <p>You can search for specific commands by entering:</p> <pre><code>ujust | grep \"&lt;search keyword(s)&gt;\"\n</code></pre> <ul> <li><code>install-</code>: Install program, there is no configuration or uninstall commands at this time.     - Warning: Some of the applications avaliable to install as a <code>ujust</code> command can end up layering packages to your system.</li> <li><code>get-</code>: Install an \"extension\" like Decky plugins, and if it is an extension then it can use <code>get-</code> too.</li> <li><code>setup-</code>: Install program, provides uninstall and configuration options for after install.</li> <li><code>configure-</code>: Configure something that came by default on the image.<ul> <li>If it must be installed first, then it will be in <code>setup-</code>.</li> </ul> </li> <li><code>toggle-</code>: Enables or disables a feature or setting.<ul> <li>Selection might be automatic or manual depending on implementation.</li> </ul> </li> <li><code>fix-</code>: Fixes, patches or works around an issue.</li> <li><code>distrobox-</code>: Distrobox exclusive verb intended to make container usage easier.</li> <li><code>foo</code>: Replace this with whatever the command is called.<ul> <li>These are shortcuts that we have deemed necessary to not have a verb.<ul> <li>Examples: <code>ujust update</code> &amp; <code>ujust enroll-secureboot-key</code></li> </ul> </li> </ul> </li> </ul>"},{"location":"Installing_and_Managing_Software/ujust/#view-each-ujust-scripts-source-code","title":"View each <code>ujust</code> script's source code","text":"<p>If you would like to see what each script does for each command then open a host terminal and enter:</p> <pre><code>ujust --show &lt;command&gt;\n</code></pre> <p>Alternatively, you can find the <code>ujust</code> commands locally in: <code>/usr/share/ublue-os/just</code></p> <p>Note</p> <p>This directory also shows hidden <code>ujust</code> commands.</p>"},{"location":"Installing_and_Managing_Software/ujust/#ujust-script-overview","title":"<code>ujust</code> Script Overview","text":"<p>These are just some of the common Bazzite <code>ujust</code> script examples, there are much more available which are viewable with <code>ujust --choose</code> as mentioned above.</p>"},{"location":"Installing_and_Managing_Software/ujust/#maintenance-scripts","title":"Maintenance Scripts","text":"<ul> <li>ujust update - updates system, flatpaks, and containers all at once</li> <li>ujust configure-grub - Configures GRUB boot menu visibility</li> <li>ujust fix-reset-steam - Reset the Steam folder back to a fresh state without removing games, music, saves, etc. Very useful if Steam is giving trouble or if you are getting a blank screen in Game Mode</li> <li>ujust fix-proton-hang - Force terminates all processes related to wine and proton. Useful if you can't launch games after a game fails to close properly</li> <li>ujust bios - Reboots straight into this device's BIOS/UEFI screen</li> <li>ujust restart-pipewire - Crackling audio? Restarting Pipewire sometimes fixes that</li> <li>ujust enroll-secure-boot-key - Enrolls the Nvidia driver &amp; KMOD signing key for secure boot. You'll need this if you want to use Bazzite with Secure Boot enabled</li> <li>ujust clean-system - Cleans up old unused podman images, volumes, flatpak packages and rpm-ostree content</li> </ul>"},{"location":"Installing_and_Managing_Software/ujust/#configurationenabling-scripts","title":"Configuration/Enabling Scripts","text":"<ul> <li>ujust setup-waydroid - a configuration helper for Waydroid. More information in Waydroid Setup Guide</li> <li>ujust setup-virtualization - setup and configure virtualization and vfio</li> <li>ujust setup-sunshine - toggle Sunshine Game Streaming host on or off</li> <li>ujust setup-luks-tpm-unlock - enable auto LUKS unlock via TPM</li> <li>ujust setup-decky - Install and configure Decky Loader</li> <li>ujust setup-boot-windows-steam - Adds a script in Steam to boot Windows which is useful for dual-boot setups</li> <li>ujust enable-tailscale - Enables support for Tailscale</li> <li>ujust enable-supergfxctl - Enable Supergfxctl, a GPU switcher for hybrid laptops</li> <li>ujust bazzite-cli - Bazzite CLI mod for Bluefin styled cli enhancements. More information in Bazzite Command Line Tools</li> </ul>"},{"location":"Installing_and_Managing_Software/ujust/#troubleshooting-scripts","title":"Troubleshooting Scripts","text":"<ul> <li>ujust logs-last-boot - Shows all messages from last boot</li> <li>ujust logs-this-boot - Shows all messages from this boot</li> <li>ujust device-info - Gathers useful device information to a pastebin. This is very useful for providing information when creating support tickets.</li> </ul>"},{"location":"Installing_and_Managing_Software/ujust/#project-website","title":"Project Website","text":"<p>https://just.systems/man/en/</p>"},{"location":"Installing_and_Managing_Software/Updates_Rollbacks_and_Rebasing/","title":"Updates, Rollbacks, and Rebasing","text":""},{"location":"Installing_and_Managing_Software/Updates_Rollbacks_and_Rebasing/#updates","title":"Updates","text":"<p>Updates are automatic on Desktop images and manually done on Bazzite-Deck images, and both Bazzite variants upgrade everything at both a system-level and user-installed applications during the updating process.</p> <p>Updating Guide</p>"},{"location":"Installing_and_Managing_Software/Updates_Rollbacks_and_Rebasing/#rollbacks","title":"Rollbacks","text":"<p>Swap back to a previous system update if there are major issues after updating via the GRUB menu or the <code>rpm-ostree rollback</code> command.</p> <p>Rollbacks Guide</p>"},{"location":"Installing_and_Managing_Software/Updates_Rollbacks_and_Rebasing/#rebasing","title":"Rebasing","text":"<p>Important</p> <p>Do not rebase to a different desktop environment than the one you are currently using, please backup and reinstall instead.</p> <p>Rebase to Bazzite builds from the last 90 days, change Bazzite update channels, swap between the Desktop and Bazzite-Deck images, or move completely to a different Fedora Atomic Desktop image.</p> <p>Rebase Guide</p>"},{"location":"Installing_and_Managing_Software/Updates_Rollbacks_and_Rebasing/#bazzite-rollback-helper-tool","title":"Bazzite Rollback Helper Tool","text":"<p>Utility to assist with rolling back to older Bazzite images, changing update branches, or swapping to a different Bazzite image.</p> <p>Bazzite's Rollback Helper Utility Guide</p>"},{"location":"Installing_and_Managing_Software/Updates_Rollbacks_and_Rebasing/bazzite_rollback_helper/","title":"Bazzite Rollback Helper (<code>brh</code>)","text":"<p>Note</p> <p>The Bazzite Portal integrates the Bazzite Rollback Helper commands into a graphical view.</p>"},{"location":"Installing_and_Managing_Software/Updates_Rollbacks_and_Rebasing/bazzite_rollback_helper/#purpose","title":"Purpose","text":"<p><code>bazzite-rollback-helper</code> is a command-line tool for rolling back system upgrades or changing the update stream.  Rollback to a Bazzite build within the last 90 days using a command-line utility that assists with rollbacks, rebasing, and outputs information on your current Bazzite image.</p>"},{"location":"Installing_and_Managing_Software/Updates_Rollbacks_and_Rebasing/bazzite_rollback_helper/#using-bazzite-rollback-helper","title":"Using <code>bazzite-rollback-helper</code>","text":"<p>Open a host terminal and enter:</p> <pre><code>bazzite-rollback-helper\n</code></pre> <p>There is also an alias which is less typing for those on handhelds or HTPC setups without a keyboard:</p> <pre><code>brh\n</code></pre>"},{"location":"Installing_and_Managing_Software/Updates_Rollbacks_and_Rebasing/bazzite_rollback_helper/#options-available","title":"Options Available:","text":"<ul> <li><code>list</code> = List images from the last 90 days that can rebased to.</li> <li><code>rollback</code> = Rollback to the previous deployment on the next reboot.</li> <li><code>current</code> = Show information about your current deployment and image.</li> <li><code>rebase</code> = Switch to another build, update branch, or a different Fedora image at your own risk.</li> </ul>"},{"location":"Installing_and_Managing_Software/Updates_Rollbacks_and_Rebasing/bazzite_rollback_helper/#examples","title":"Examples","text":"<p><code>bazzite-rollback-helper list</code> will list available bazzite images.</p> <p><code>bazzite-rollback-helper rebase &lt;image-name:stable&gt;</code> to rebase to an earlier image, update branch, or different Bazzite image (Desktop vs. Bazzite-Deck).  Find a version from the <code>list</code> command.</p>"},{"location":"Installing_and_Managing_Software/Updates_Rollbacks_and_Rebasing/bazzite_rollback_helper/#rebasing-to-an-older-bazzite-image","title":"Rebasing to an older Bazzite image","text":"<p>Example: <code>bazzite-rollback-helper rebase stable-40.20240930.0</code> <sub>(This image is an example and no longer can be rolled back to as it is too old.)</sub></p> <p>Rebasing to an image will lock you to that OS image which means new features and security updates will no longer be applied until you rebase back to the Stable update channel.</p> <p>Get back to normal OS updates later after the bug has been squashed that prevents you from running the Stable update channel: <code>bazzite-rollback-helper rebase stable</code></p>"},{"location":"Installing_and_Managing_Software/Updates_Rollbacks_and_Rebasing/bazzite_rollback_helper/#bazzite-rollback-helper-video-tutorial","title":"Bazzite Rollback Helper Video Tutorial","text":""},{"location":"Installing_and_Managing_Software/Updates_Rollbacks_and_Rebasing/rebase_guide/","title":"Rebase Guide","text":""},{"location":"Installing_and_Managing_Software/Updates_Rollbacks_and_Rebasing/rebase_guide/#what-is-rebasing","title":"What is Rebasing?","text":"<p>Warning</p> <p>Rebasing between different desktop environments (e.g. KDE Plasma to GNOME) may cause issues and is unsupported.</p> <p>Rebasing allows users to switch to a different image without having to reinstall and lose personal files and application data.</p> <p>It is recommended to use the Bazzite Rollback Helper utility.</p>"},{"location":"Installing_and_Managing_Software/Updates_Rollbacks_and_Rebasing/rebase_guide/#rebase-scenarios","title":"Rebase Scenarios","text":"<ul> <li>Rebase to specific images of older builds within the last 90 days if issues are occurring on the newest build of Bazzite.</li> <li>Rebase to other Fedora Atomic Desktop images including other Bazzite images.<ul> <li>Do not rebase between different desktop environments.</li> </ul> </li> </ul>"},{"location":"Installing_and_Managing_Software/Updates_Rollbacks_and_Rebasing/rebase_guide/#how-do-i-swap-between-bazzite-images","title":"How do I swap between Bazzite images?","text":"<p>See what channel or build you are on by entering this command in a host terminal:</p> <pre><code>rpm-ostree status\n</code></pre> <p>Check under \"Deployments:\" and the output should be similar to: <pre><code> \u25cf ostree-image-signed:docker://ghcr.io/ublue-os/[*image*]:[*channel*]\n</code></pre></p> <p>Switch to another Bazzite variant by entering the command for each specific image.</p> <p>Open the terminal and enter:</p> <pre><code>rpm-ostree rebase &lt;image&gt;\n</code></pre>"},{"location":"Installing_and_Managing_Software/Updates_Rollbacks_and_Rebasing/rebase_guide/#example","title":"Example:","text":"<p>Warning</p> <p>Rebasing between different desktop environments (e.g. KDE Plasma to GNOME) may cause issues and is unsupported.</p> <pre><code>rpm-ostree rebase ostree-image-signed:docker://ghcr.io/ublue-os/bazzite-deck:stable\n</code></pre> <p>For rebasing to the KDE Plasma version of the Bazzite-Deck image.</p>"},{"location":"Installing_and_Managing_Software/Updates_Rollbacks_and_Rebasing/rebase_guide/#how-do-i-change-the-bazzites-update-branch-stable-testing-and-unstable","title":"How do I change the Bazzite's update branch? (Stable, Testing, and Unstable)","text":"<p>There are two update branches intended for end-users:</p> <ul> <li>Stable (<code>:stable</code>)<ul> <li>Default branch that's used in normal Bazzite installations.</li> </ul> </li> <li>Testing (<code>:testing</code>)<ul> <li>Get a sneak peak of future Bazzite builds before release.</li> <li>Bugs may frequently appear.</li> <li>Encouraged to rebase back to <code>:stable</code> after testing a major release.</li> </ul> </li> </ul>"},{"location":"Installing_and_Managing_Software/Updates_Rollbacks_and_Rebasing/rebase_guide/#the-unstable-branch","title":"The Unstable Branch","text":"<p>This is intended for Bazzite's core contributors and maintainers only and is used for major changes that need frequent testing. The unstable branch can fall behind updates even in the stable branch since it is testing specific major changes and is not something that is built on a schedule.</p>"},{"location":"Installing_and_Managing_Software/Updates_Rollbacks_and_Rebasing/rebase_guide/#switching-update-branches-in-steam-gaming-mode","title":"Switching Update Branches in Steam Gaming Mode","text":"<p>Bazzite-Deck images can switch branches in <code>Settings &gt; System &gt; OS Update Channel</code> in Steam Gaming Mode.</p> <p>If you enabled advanced update channel, then additional options will appear. The options map as the following:</p> <pre><code>Stable (:stable)\nRelease Candidate (:testing)\nBeta (:testing)\nBeta Candidate (:unstable)\nMain (:unstable)\n</code></pre>"},{"location":"Installing_and_Managing_Software/Updates_Rollbacks_and_Rebasing/rebase_guide/#example_1","title":"Example:","text":"<pre><code>rpm-ostree rebase ostree-image-signed:docker://ghcr.io/ublue-os/bazzite:testing\n</code></pre> <p>For the testing branch on the AMD/Intel Desktop image.</p>"},{"location":"Installing_and_Managing_Software/Updates_Rollbacks_and_Rebasing/rebase_guide/#rebasing-to-older-builds","title":"Rebasing to older builds","text":"<p>Attention</p> <p>You will have to rebase back to <code>:stable</code> once you want to upgrade to the newest release.</p> <p>Warning</p> <p>Switching to older Bazzite builds will not bring new updates until you upgrade back to <code>:stable</code> which means there will be no security updates until you rebase back to the stable branch.</p> <p>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 <code>:stable</code> to update the system to receive the newest build.</p> <p>View the list of available stable builds by entering:</p> <pre><code>skopeo list-tags docker://ghcr.io/ublue-os/bazzite | grep -- \"stable-\" | sort -rV\n</code></pre> <p>Rebasing to a specific build requires users to open a host terminal and enter:</p> <pre><code>rpm-ostree rebase ostree-image-signed:docker://ghcr.io/ublue-os/IMAGE-NAME:VERSION-YEARMONTHDAY\n</code></pre> <p>Example:</p> <pre><code>rpm-ostree rebase ostree-image-signed:docker://ghcr.io/ublue-os/bazzite-deck:39-20240113\n</code></pre> <p>For the Jan. 13<sup>th</sup> 2024 <code>bazzite-deck</code> (Fedora 39) build.</p> <p>(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.)</p>"},{"location":"Installing_and_Managing_Software/Updates_Rollbacks_and_Rebasing/rolling_back_system_updates/","title":"Rollbacks","text":""},{"location":"Installing_and_Managing_Software/Updates_Rollbacks_and_Rebasing/rolling_back_system_updates/#rolling-back-upgrades","title":"Rolling Back Upgrades","text":"<p>Swap back to a previous system update if there are major issues after updating via the GRUB menu or the <code>rpm-ostree rollback</code> command or using the Bazzite Rollback Helper.</p>"},{"location":"Installing_and_Managing_Software/Updates_Rollbacks_and_Rebasing/rolling_back_system_updates/#how-do-i-rollback-a-system-update","title":"How do I rollback a system update?","text":"<p>A rollback to the previous system deployment can be done by entering this command in a host terminal:</p> <pre><code>rpm-ostree rollback\n</code></pre>"},{"location":"Installing_and_Managing_Software/Updates_Rollbacks_and_Rebasing/rolling_back_system_updates/#using-the-bazzite-rollback-helper-brh-utility","title":"Using the Bazzite Rollback Helper (<code>brh</code>) Utility","text":"<p>Rollback to an older Bazzite image from the last 90 days using the <code>brh</code> command.</p>"},{"location":"Installing_and_Managing_Software/Updates_Rollbacks_and_Rebasing/rolling_back_system_updates/#before-booting-bazzite-grub","title":"Before Booting Bazzite (GRUB)","text":"<p>Note</p> <p>Controls may vary with different handhelds or HTPC setups to navigate the menu and an external physical keyboard may be required to rollback in GRUB.</p> <p>Rollback can also be done in the GRUB menu (which appears before booting into Bazzite) by choosing the previous boot entry before booting to the desktop. It shows your current (<code>:0</code>) and your previous (<code>:1</code>) deployments. Your personal files will not be affected by this, and you can still update to the newest builds after rolling back.</p>"},{"location":"Installing_and_Managing_Software/Updates_Rollbacks_and_Rebasing/rolling_back_system_updates/#how-do-i-save-my-current-deployment","title":"How do I save my current deployment?","text":"<p>You can pin your current deployment with this command:</p> <pre><code>sudo ostree admin pin 0\n</code></pre> <p>In a host terminal for a backup save state of your current deployment to rollback to if a new system update causes issues.</p>"},{"location":"Installing_and_Managing_Software/Updates_Rollbacks_and_Rebasing/rolling_back_system_updates/#how-do-i-save-my-previous-deployment","title":"How do I save my previous deployment?","text":"<p>You can pin your previous deployment with this command:</p> <pre><code>sudo ostree admin pin 1\n</code></pre> <p>In a host terminal for a backup save state of your previous deployment to rollback if the current deployment has issues.</p>"},{"location":"Installing_and_Managing_Software/Updates_Rollbacks_and_Rebasing/rolling_back_system_updates/#how-do-i-unpin-a-deployment-if-i-saved-it","title":"How do I unpin a deployment if I saved it?","text":"<p>Unpin saved current deployment:</p> <pre><code>sudo ostree admin pin --unpin 0\n</code></pre> <p>Unpin saved previous deployment:</p> <pre><code>sudo ostree admin pin --unpin 1\n</code></pre> <p>View all deployment index numbers:</p> <pre><code>rpm-ostree status -v\n</code></pre> <p>Unpin saved deployment:</p> <pre><code>sudo ostree admin pin --unpin &lt;index number&gt;\n</code></pre>"},{"location":"Installing_and_Managing_Software/Updates_Rollbacks_and_Rebasing/rolling_back_system_updates/#application-update-downgrades","title":"Application Update Downgrades","text":"<p>Read about the pre-installed Warehouse application to downgrade applications in the Bazaar App Store (Flatpak) documentation.</p>"},{"location":"Installing_and_Managing_Software/Updates_Rollbacks_and_Rebasing/updating_guide/","title":"Update Guide","text":""},{"location":"Installing_and_Managing_Software/Updates_Rollbacks_and_Rebasing/updating_guide/#updating-bazzite","title":"Updating Bazzite","text":"<p>Attention</p> <p>It is required to have 3% free storage of your total drive that Bazzite is installed on to update properly.</p> <p>Bazzite updates all of the changes made specifically in Bazzite itself, updates from Fedora's base packages upstream, graphic drivers, and user software installed from Bazaar.</p>"},{"location":"Installing_and_Managing_Software/Updates_Rollbacks_and_Rebasing/updating_guide/#desktop-images","title":"Desktop Images","text":"<ul> <li>System updates happen automatically daily on a schedule and when the hardware is not under heavy use, like playing video games.     - There is a check in-place to only update the image when your CPU, battery, and RAM usage meets certain requirements.</li> <li>Updates will be downloaded in the background and will apply on the next reboot and should contain the newest build of Bazzite.     - An upgrade can be forced with the System Update tool at your own convenience.</li> <li>Updates upgrade system packages, Steam, and installed applications when available. </li> </ul>"},{"location":"Installing_and_Managing_Software/Updates_Rollbacks_and_Rebasing/updating_guide/#bazzite-deck-images","title":"Bazzite-Deck Images","text":"<ul> <li>Updates can be managed in Steam Gaming Mode manually by the user.<ul> <li>Open: Steam Menu &gt; Settings &gt; System &gt; Check for Updates &gt; Apply<ul> <li>Reboot to apply system upgrades.</li> </ul> </li> </ul> </li> <li>Updates upgrade system packages, Steam, and installed applications when available.</li> </ul>"},{"location":"Installing_and_Managing_Software/Updates_Rollbacks_and_Rebasing/updating_guide/#terminal-command-manually-upgrade-all-images","title":"Terminal Command (Manually Upgrade) [All Images):","text":"<pre><code>ujust update\n</code></pre>"},{"location":"Installing_and_Managing_Software/Updates_Rollbacks_and_Rebasing/updating_guide/#do-i-have-to-reboot-immediately-after-every-system-update","title":"Do I have to reboot immediately after every system update?","text":"<p>No, but the system upgrade will not apply until the next reboot.  User-installed applications from Bazaar can be upgraded without rebooting.</p> <ul> <li>Desktop images: While your device is running, newer updates will still download in the background once a day, and will be waiting to be applied until the device is rebooted.</li> <li>Bazzite-Deck images: Updates will be checked daily and can be downloaded at your leisure similar to how SteamOS handles upgrades.</li> </ul>"},{"location":"Installing_and_Managing_Software/Updates_Rollbacks_and_Rebasing/updating_guide/#how-do-i-view-the-changelog-for-each-update","title":"How do I view the changelog for each update?","text":"<p>Changelogs for each Bazzite can be found on Github.</p>"},{"location":"Installing_and_Managing_Software/Updates_Rollbacks_and_Rebasing/updating_guide/#metered-limited-network-connections-data-caps","title":"Metered / Limited Network Connections &amp; Data Caps","text":"<p>Note</p> <p>This is an unsupported configuration since updates are expected to be running daily for both the operating system and applications.</p> <p>Open the System Settings of your desktop environment and turn on the setting relating to a metered connection (Data caps or incur charges).  This setting will pause automatic updates for Bazzite.</p>"}]}