Option reference
Every steamix.* option, generated from the declarations in
steamix/modules/nixos. The Options page is the curated
tour — what to reach for and why; this page is the complete,
cannot-drift listing.
steamix.enable
Whether to enable the SteamOS-like Gaming Mode experience.
Type: boolean
Default:
false
Example:
true
Declared by:
steamix.autoStart
Boot straight into Gaming Mode. This owns the login path — see
steamix.loginManager for which display manager does it — so
it cannot be combined with another one. Disable it to merely register
the “Steam” session with whatever display manager you already run.
Type: boolean
Default:
true
Declared by:
steamix.binaryCache.enable
Download Steamix’s own packages from its binary cache,
steamix.cachix.org, instead of compiling them: SteamOS Manager,
Decky Loader and the 32-bit gamescope WSI layer, which
cache.nixos.org does not carry. Adds the cache and its public key
to nix.settings, next to whatever is already there.
On by default because it asks for no trust beyond what importing this module already does: the module runs as root, and the cache is signed with a key pinned here. It only helps when the machine’s nixpkgs is a revision Steamix’s CI built against; otherwise Nix builds locally, as it would without the cache. Turn it off to build everything yourself.
Type: boolean
Default:
true
Declared by:
steamix.decky-loader.enable
Whether to enable Decky Loader, the Steam Deck plugin loader.
Type: boolean
Default:
false
Example:
true
Declared by:
steamix.decky-loader.package
The Decky Loader package to run, or null when none is available.
nixpkgs does not package Decky Loader, so this defaults to null
unless an overlay provides pkgs.decky-loader. With null the module
does nothing and warns instead of breaking evaluation.
Type: null or package
Default:
pkgs.decky-loader or null
Declared by:
steamix.decky-loader.extraPackages
Extra packages on the loader’s PATH. Some plugins shell out to
tools that are not part of a minimal system.
Type: list of package
Default:
[ ]
Example:
[ pkgs.curl pkgs.unzip ]
Declared by:
steamix.decky-loader.extraPythonPackages
Extra Python packages importable by plugins, as a function of the interpreter’s package set.
Type: function that evaluates to a(n) list of package
Default:
pythonPackages: [ ]
Example:
pythonPackages: with pythonPackages; [ hid ]
Declared by:
steamix.decky-loader.plugins
Plugins to install declaratively. Each is symlinked into the plugin
directory, which Decky scans for directories containing a
plugin.json; it resolves symlinks, so store paths load normally.
This composes with the in-game store rather than replacing it: plugins installed through Decky’s UI are ordinary directories alongside these symlinks and keep working. What a plugin declared here gives up is Decky’s own updater — the version is whatever the package pins — and uninstalling it from the UI only removes the symlink until the next boot restores it.
Per-plugin settings and data are unaffected either way: Decky keeps
those in settings/ and data/ beside the plugin directory, never
inside it, which is what lets these be read-only.
Type: list of package
Default:
[ ]
Example:
with pkgs.deckyPlugins; [ hltb-for-deck protondb-decky ]
Declared by:
steamix.decky-loader.stateDir
Directory holding installed plugins and their data.
Type: absolute path
Default:
"/var/lib/decky-loader"
Declared by:
steamix.decky-loader.user
The unprivileged user plugins are run as. The loader itself runs as root and drops to this user; see the note in the service definition.
Type: string
Default:
"decky"
Declared by:
steamix.desktopSession
Name of the Wayland session started by “Switch to Desktop” in
Gaming Mode (a session name from
services.displayManager.sessionData.sessionNames, i.e.
the basename of a wayland-sessions/*.desktop file). When null,
switching to the desktop relaunches Gaming Mode.
Type: null or string
Default:
null
Example:
"gnome"
Declared by:
steamix.emulation.enable
Whether to enable emulation: RetroArch with a set of libretro cores.
Type: boolean
Default:
false
Example:
true
Declared by:
steamix.emulation.kiosk.enable
Whether to enable booting straight into RetroArch, full screen, for machines that run
nothing else on their display (no Steam, no desktop). It runs as
steamix.emulation.kiosk.user in the cage compositor, and
is started again if it exits
.
Type: boolean
Default:
false
Example:
true
Declared by:
steamix.emulation.kiosk.user
The user RetroArch runs as in kiosk mode.
Type: null or string
Default:
config.steamix.user
Declared by:
steamix.emulation.retroarch.package
The retroarch-bare package to use. The frontend alone; steamix.emulation.retroarch.cores
and steamix.emulation.retroarch.settings are wrapped
around it.
Type: package
Default:
pkgs.retroarch-bare
Declared by:
steamix.emulation.retroarch.cores
The libretro cores RetroArch can run, from pkgs.libretro. The
default ones are free software.
Type: list of package
Default:
with pkgs.libretro; [ nestopia bsnes mgba pcsx-rearmed ]
Example:
# unfree, but much faster on small ARM boards
with pkgs.libretro; [ nestopia snes9x genesis-plus-gx mgba pcsx-rearmed ]
Declared by:
steamix.emulation.retroarch.finalPackage
The RetroArch that is installed.
Type: package (read only)
Default: RetroArch with the cores and settings above
Declared by:
steamix.emulation.retroarch.settings
retroarch.cfg settings, applied over the user’s own
configuration on every start, so these always win over what is
changed in RetroArch’s menus.
Type: attribute set of string
Default:
{ }
Example:
{
menu_driver = "ozone";
video_fullscreen = "true";
}
Declared by:
steamix.gamescope.args
Extra arguments appended to the gamescope command line, after the ones this module derives from the options above.
Type: list of string
Default:
[ ]
Example:
[
"--output-width"
"3840"
"--output-height"
"2160"
]
Declared by:
steamix.gamescope.env
Extra environment variables for the Gaming Mode session. These are exported last, so they override the module’s own defaults.
Type: attribute set of string
Default:
{ }
Example:
{
GAMESCOPE_MODE_SAVE_FILE = "/tmp/modes.cfg";
}
Declared by:
steamix.gamescope.wsi.enable
Install the gamescope WSI Vulkan layer
(VK_LAYER_FROG_gamescope_wsi) and enable it for the session.
The layer is how games present through gamescope directly — it
carries frame pacing, the fps limiter, and HDR swapchains.
Without it HDR content is tonemapped down to SDR.
Type: boolean
Default:
true
Declared by:
steamix.gamescope.wsi.package
The gamescope-wsi package to use. Added to hardware.graphics.extraPackages. The layer
speaks a versioned protocol to gamescope, so override this to keep
it in step with a non-default
programs.gamescope.package.
Type: package
Default:
pkgs.gamescope-wsi
Declared by:
steamix.gamescope.wsi.package32
The gamescope-wsi package to use. Added to hardware.graphics.extraPackages32. Needed by
32-bit games and by Proton’s 32-bit halves.
Type: package
Default:
pkgs.pkgsi686Linux.gamescope-wsi
Declared by:
steamix.hdr.enable
Allow HDR output in Gaming Mode: starts gamescope with
--hdr-enabled and tells Steam the session supports HDR, which is
what puts the HDR toggle in Gaming Mode’s display settings.
Harmless on SDR displays — gamescope only drives HDR when the
connected output actually advertises it. Requires the gamescope WSI
Vulkan layer (steamix.gamescope.wsi.enable) for games to
hand HDR swapchains through.
Type: boolean
Default:
true
Declared by:
steamix.heroic.enable
Whether to enable Heroic Games Launcher, for Epic, GOG and Amazon Prime Gaming games.
Type: boolean
Default:
false
Example:
true
Declared by:
steamix.heroic.package
The heroic package to use. nixpkgs’ heroic runs the launcher in an FHS environment with the
libraries its games and Wine builds expect. Use
pkgs.heroic.override { extraPkgs = pkgs: [ ... ]; } to add more.
Type: package
Default:
pkgs.heroic
Declared by:
steamix.library.boilr.enable
Whether to enable syncing games from other launchers (Heroic, Legendary, Lutris, itch.io, Bottles, Flatpak, …) into Steam’s library with BoilR, on every login before Steam starts, so Gaming Mode can launch them .
Type: boolean
Default:
false
Example:
true
Declared by:
steamix.library.boilr.package
The boilr package to use.
Type: package
Default:
pkgs.boilr
Declared by:
steamix.library.boilr.settings
BoilR’s configuration, written to ~/.config/boilr/config.toml on
every login (see BoilR’s
configuration reference).
Anything not set keeps BoilR’s default, which detects most launchers
on its own. Steamix sets steam.optimize_for_big_picture, and enables
SteamGridDB only when steamix.library.boilr.steamGridDbKeyFile
is set; both can be overridden here.
Because the file is rewritten on every login, this is the source of truth: changes made in BoilR’s own window do not last.
Type: TOML value
Default:
{ }
Example:
{
lutris.enabled = false;
steam.create_collections = true;
# launch these Heroic games directly instead of through Heroic
heroic.launch_games_through_heroic = [ "Fortnite" ];
heroic.default_launch_through_heroic = true;
}
Declared by:
steamix.library.boilr.steamGridDbKeyFile
A file holding a SteamGridDB API key,
read at login, so the key never enters the Nix store. With it, BoilR
downloads covers, banners and logos for every game it adds. It must
be readable by steamix.user. null syncs without artwork.
Type: null or string
Default:
null
Example:
"/run/secrets/steamgriddb"
Declared by:
steamix.library.boilr.timeout
Seconds a sync may take before Steam is started anyway. The first sync with artwork downloads images for every game; later ones only for new games.
Type: positive integer, meaning >0
Default:
120
Declared by:
steamix.loginManager
Which display manager owns the login path when
steamix.autoStart is on. Two shapes, and the difference is
not cosmetic:
greetd is self-contained. It needs nothing outside nixpkgs, and
session switching goes through the steamos-session-select script
this module ships. The cost is that greetd registers its sessions as
logind class greeter, type tty, so the module corrects that with a
pam_env rule for desktop compositors to be willing to start.
sddm is what SteamOS itself runs, and matches what Valve’s software
expects. Sessions come out as class user, type wayland with no
correction needed, and switching goes through SteamOS Manager’s
SessionManagement1 interface — the path the Steam client prefers.
It requires steamix.manager and therefore a
steamos-manager package, which nixpkgs does not have; an assertion
will tell you if it is missing.
Type: one of “greetd”, “sddm”
Default:
"greetd"
Declared by:
steamix.losslessScaling.enable
Whether to enable Lossless Scaling frame generation for Steam’s games, through the lsfg-vk Vulkan layer. Needs Lossless Scaling installed from Steam; for lsfg-vk 2.x, on its “lsfg-vk” beta branch .
Type: boolean
Default:
false
Example:
true
Declared by:
steamix.losslessScaling.package
The lsfg-vk package to use. From 2.0, lsfg-vk is licensed CC BY-NC-ND 4.0, which nixpkgs treats as
unfree, so nixpkgs.config.allowUnfree (or a predicate allowing
lsfg-vk) has to permit it; the licence also forbids redistribution,
so no binary cache carries it and it builds locally. NixOS 26.05
ships the MIT-licensed 1.0, whose config format differs; both work.
Type: package
Default:
pkgs.lsfg-vk
Declared by:
steamix.losslessScaling.allowHalfPrecision
Use half-precision (FP16) arithmetic where the GPU supports it, for 2 to 3 times faster frame generation. lsfg-vk 2.x only.
Type: boolean
Default:
true
Declared by:
steamix.losslessScaling.deckyPlugin.enable
Manage lsfg-vk from Gaming Mode with the Decky LSFG-VK plugin: its Quick Access menu has per-game frame generation settings, the way it works on SteamOS. Press its “Install lsfg-vk” button once.
The plugin installs its own lsfg-vk into the user’s home, so Steamix
does not install the layer, config or UI while it is on. It cannot
be combined with profiles, which would be a config the plugin
cannot change. It needs Decky to run plugins as the Steam user
(steamix.decky-loader.user set to steamix.user),
as SteamOS does, because that is whose home it installs into.
Type: boolean
Default:
on when Decky Loader is enabled, profiles is empty, and Decky runs
plugins as steamix.user
Declared by:
steamix.losslessScaling.deckyPlugin.package
The plugin, from Steamix’s overlay by default. It carries lsfg-vk’s own build (CC BY-NC-ND 4.0), so it is unfree, like lsfg-vk 2.x.
Type: null or package
Default:
pkgs.deckyPlugins.decky-lsfg-vk or null
Declared by:
steamix.losslessScaling.dll
Where Lossless Scaling’s DLL is, when it is not in a Steam library
lsfg-vk searches by itself (the default ones under ~/.local/share
and ~/.steam). A directory or the DLL itself. Only written in the
declarative mode; otherwise set it in the config yourself.
Type: null or string
Default:
null
Example:
"/mnt/games/SteamLibrary/steamapps/common/Lossless Scaling"
Declared by:
steamix.losslessScaling.profiles
Frame generation profiles, by name. When any are set, Steamix writes
the whole config to /etc/lsfg-vk/conf.toml and points every session
at it, so it is read-only: lsfg-vk’s UI and the Decky plugin cannot
change it. Leave this empty to configure lsfg-vk interactively
instead, in ~/.config/lsfg-vk/conf.toml.
Type: attribute set of (submodule)
Default:
{ }
Example:
{
elden-ring = {
activeIn = [ "1245620" ];
multiplier = 2;
flowScale = 0.75;
};
}
Declared by:
steamix.losslessScaling.profiles.<name>.activeIn
Games this profile applies to: Linux executables (matched as a
suffix of the path), Windows .exe names for Proton games, process
names, or Steam App IDs. lsfg-vk 1.x matches executables and
process names only, not Steam App IDs.
Type: non-empty (list of string)
Example:
[
"1245620"
"eldenring.exe"
]
Declared by:
steamix.losslessScaling.profiles.<name>.flowScale
Resolution of the motion estimation, as a fraction of the game’s. Lower is faster and less accurate; on a large display 0.5 to 0.75 often looks the same.
Type: integer or floating point number between 0.25 and 1 (both inclusive)
Default:
1.0
Declared by:
steamix.losslessScaling.profiles.<name>.hdrMode
Treat the game’s output as HDR. lsfg-vk 1.x only; 2.x detects it.
Type: boolean
Default:
false
Declared by:
steamix.losslessScaling.profiles.<name>.multiplier
Frames shown per rendered frame: 2 doubles the frame rate.
Type: integer between 2 and 20 (both inclusive)
Default:
2
Declared by:
steamix.losslessScaling.profiles.<name>.pacingMode
Frame pacing. lsfg-vk 2.x only; ignored by 1.x.
Type: one of “vsync”, “none”
Default:
"vsync"
Declared by:
steamix.losslessScaling.profiles.<name>.performanceMode
Use the lighter frame generation model.
Type: boolean
Default:
false
Declared by:
steamix.losslessScaling.support32Bit.enable
Whether to enable the 32-bit layer as well, for 32-bit games. It is a second local build of lsfg-vk .
Type: boolean
Default:
false
Example:
true
Declared by:
steamix.losslessScaling.support32Bit.package
The lsfg-vk package to use.
Type: package
Default:
pkgs.pkgsi686Linux.lsfg-vk
Declared by:
steamix.losslessScaling.ui.enable
Whether to enable lsfg-vk’s configuration UI, for editing profiles from Desktop Mode
when profiles is empty
.
Type: boolean
Default:
false
Example:
true
Declared by:
steamix.losslessScaling.ui.package
The lsfg-vk-ui package to use. The UI writes the config format of its own major version, so keep
it on the same major version as steamix.losslessScaling.package;
Steamix warns when they differ. When overriding the layer, for
example to a newer nixpkgs’ lsfg-vk, override this from the same
nixpkgs.
Type: package
Default:
pkgs.lsfg-vk-ui
Declared by:
steamix.manager.enable
Whether to enable SteamOS Manager, the OS-integration daemon Steam talks to.
Type: boolean
Default:
false
Example:
true
Declared by:
steamix.manager.package
The SteamOS Manager package, or null when none is available.
nixpkgs does not package it, so this is null unless an overlay
provides pkgs.steamos-manager; the module then does nothing and warns
rather than failing to evaluate.
Type: null or package
Default:
pkgs.steamos-manager or null
Declared by:
steamix.mangoapp.enable
Run gamescope’s mangoapp overlay, which is what backs Steam’s built-in “Performance Overlay” levels in Gaming Mode.
Type: boolean
Default:
true
Declared by:
steamix.mangoapp.package
The mangohud package to use. Supplies the mangoapp binary gamescope spawns for the overlay.
mangoapp talks to gamescope over X atoms and a message queue, so
when programs.gamescope.package is overridden to a much
newer gamescope, override this to match.
Type: package
Default:
pkgs.mangohud
Declared by:
steamix.mangoapp.backgroundAlpha
Opacity of the performance overlay’s backdrop, from 0 (invisible)
to 1 (solid).
MangoHud defaults to 0.5, which is legible on a monitor an arm’s
length away and washes out into the game from across a living room.
null leaves MangoHud’s own default alone.
Type: null or integer or floating point number between 0 and 1 (both inclusive)
Default:
0.8
Example:
0.5
Declared by:
steamix.mangoapp.fontScale
Multiplier for the performance overlay’s size (MangoHud’s
font_scale, which scales the panel as well as the text).
MangoHud draws the overlay at a fixed size that was picked for the
Steam Deck’s 1280x800 panel, so it shrinks to an unreadable speck on
a 4K television. The default null scales it automatically against
the tallest connected output — roughly 1.8x at 1440p and 2.7x at
2160p — which keeps it about the size it is on a Deck. Set a number
to pin it, or 1 for MangoHud’s own sizing.
Type: null or (positive integer or floating point number, meaning >0)
Default:
null
Example:
2.7
Declared by:
steamix.mangoapp.pciDev
PCI address of the GPU the overlay should report on, written
domain:bus:device.function as lspci -D prints it (MangoHud’s
pci_dev).
Only meaningful on a machine with more than one GPU. MangoHud
enumerates every GPU it finds and picks one itself, which need not
be the one gamescope is rendering with — a desktop with an unused
integrated GPU can end up with an overlay reporting that chip’s
load and temperature while the games run on the discrete card.
null leaves the choice to MangoHud.
Type: null or string
Default:
null
Example:
"0000:03:00.0"
Declared by:
steamix.proton.fsr4.enable
Whether to enable a “GE-Proton (FSR 4)” compatibility tool: GE-Proton with
PROTON_FSR4_UPGRADE set, so it downloads and uses AMD’s FSR 4 DLL in
games that ship FSR 3.1. Needs an AMD RDNA 3 or RDNA 4 GPU. Choose it
per game in Steam, or as Steam’s default compatibility tool. Built
from steamix.proton.ge.package, and independent of
steamix.proton.ge.enable
.
Type: boolean
Default:
false
Example:
true
Declared by:
steamix.proton.fsr4.indicator
Draw AMD’s FSR watermark in games, which shows whether FSR 4 upscaling and frame generation are actually active.
Type: boolean
Default:
false
Declared by:
steamix.proton.fsr4.version
The FSR 4 DLL version to ask GE-Proton for. null takes the one
GE-Proton currently considers the default.
Type: null or string
Default:
null
Example:
"4.1.1"
Declared by:
steamix.proton.ge.enable
Whether to enable GE-Proton, a Proton build with extra game fixes and media codecs, as a Steam compatibility tool to pick per game .
Type: boolean
Default:
false
Example:
true
Declared by:
steamix.proton.ge.package
The proton-ge-bin package to use. Anything with a steamcompattool output, as
programs.steam.extraCompatPackages expects. Also what the
FSR 4 variant is built from.
Type: package
Default:
pkgs.proton-ge-bin
Declared by:
steamix.realtime.enable
Let gamescope renice itself into realtime scheduling (--rt), by
giving the binary cap_sys_nice via
programs.gamescope.capSysNice.
Off by default: the capability puts gamescope in secure-execution
mode, where the loader ignores LD_LIBRARY_PATH/LD_PRELOAD, which
has historically broken launching it from Steam’s FHS environment.
Turn it on and verify Gaming Mode still starts before keeping it.
Type: boolean
Default:
false
Declared by:
steamix.steamArgs
Arguments Steam is launched with inside Gaming Mode. The default is
the set Valve’s own steam-launcher uses, plus -pipewire-dmabuf
for Remote Play. -steamos3 is what ties Steam into gamescope’s
focus handling and puts “Switch to Desktop” in the power menu.
Type: list of string
Default:
[
"-gamepadui"
"-steamos3"
"-steampal"
"-steamdeck"
"-pipewire-dmabuf"
]
Declared by:
steamix.tearing.enable
Allow tearing presentation (--immediate-flips) and expose Steam’s
per-game tearing toggle. Trades visible tearing for latency; off by
default because VRR is the better answer on displays that have it.
Type: boolean
Default:
false
Declared by:
steamix.tweaks.enable
Apply the parts of SteamOS’ opinionated system tuning that are not specific to Valve’s hardware: compressed swap, an out-of-memory killer that acts before the kernel’s does, and a handful of network sysctls games trip over.
Every setting is a lib.mkDefault, so an individual one can
still be overridden without turning the whole group off.
Type: boolean
Default:
true
Declared by:
steamix.user
The user the Gaming Mode session runs as. Required when
steamix.autoStart is enabled — the machine logs this user
in without a password prompt, console-style.
Type: null or string
Default:
null
Example:
"alice"
Declared by:
steamix.vrr.enable
Allow variable refresh rate (FreeSync/G-Sync): starts gamescope with
--adaptive-sync and exposes the VRR toggle in Gaming Mode’s display
settings. Ignored by gamescope when the output does not support it.
Type: boolean
Default:
true
Declared by: