Setting up Steam Deck (Steam OS) with Nix

Introduction: Why Bother with Nix on a Gaming Device?

The Steam Deck has an immutable filesystem, where the core OS is read-only and gets completely replaced during updates. While this makes for a stable(-ish) gaming experience (especially with the root-a and root-b partitions), it poses a significant challenge for users who want to use the Deck also as Linux computer. Any software installed using traditional methods (like the pacman package manager) will be wiped out with the next system update, and also takes up rootfs space which is capped to 5GiB.

This is where Nix comes in. Nix is a package manager (also an OS: NixOS) that is uniquely suited to this immutable environment. Instead of scattering files across the system, Nix installs every package and its dependencies into its own isolated directory inside a single, persistent location: /nix/store. This allows your entire software collection—from command-line tools to development environments—to survive any SteamOS update unscathed.

While SteamOS offers Flatpak for GUI apps and Distrobox for containerized Linux environments, Nix fills a crucial gap. It allows you to install system-level tools and services that integrate directly with the host OS without being sandboxed or containerized.

This guide will walk you through the entire process, from understanding the core philosophy of Nix to installing it correctly and managing your system like a pro using the modern, declarative workflow.

The “Nix Way” - A Mental Model for Success

Before typing a single command, it’s crucial to understand that Nix operates on a different philosophy than traditional package managers. Grasping these concepts will prevent common frustrations.

The Core Concepts: Purity, Reproducibility, and the Nix Store

The Nix Store (/nix/store): This is the heart of Nix. Every package is stored in its own unique subdirectory within /nix/store. The name of this subdirectory is a cryptographic hash of all the inputs used to build it (source code, dependencies, build scripts, etc.). This means you can have multiple versions of the same package installed simultaneously without any conflicts—the infamous “dependency hell” is a thing of the past.
Purity: Nix builds packages in a “pure” or sandboxed environment. The build process is cut off from the network and most of your filesystem, and can only see the dependencies you have explicitly declared. [1, 2, 3]
Reproducibility: Because of purity and the hashing mechanism, a Nix build will produce the exact same bit-for-bit result on any machine. This is the cool thing about Nix: if it works on your machine, it will work identically on any other.

The Declarative Ideal vs. The Imperative Footgun

The most common mistake for newcomers is to treat Nix like apt or pacman.

The Imperative Footgun (nix-env): Commands like nix-env -i <package> are imperative—you’re telling the system to “do this now.” While it works, it’s considered a “footgun” in the Nix community because it modifies your system’s state without recording that change in a configuration file. This makes your setup difficult to reproduce and goes against the core philosophy of Nix.
The Declarative “Nix Way”: The proper approach is to declare the desired state of your system in configuration files. You don’t tell Nix how to install something; you simply add the package name to a list. A tool then reads this list and makes your system match it. This is the “Nix Way™”. Your configuration files become the single source of truth, which you can put in Git, share with others, and use to perfectly restore your setup on any machine.

Flakes: The Key to Perfect Reproducibility

Nix Flakes are the modern standard for managing Nix configurations. A flake is a directory containing two key files:

flake.nix: The entry point that defines your configuration’s inputs (like nixpkgs) and outputs (your packages and settings).
flake.lock: This file is automatically generated and records the exact commit hash of every input. This “locks” your dependencies, guaranteeing that rebuilding your configuration—even months later on a different computer—will use the exact same package versions, ensuring perfect reproducibility.

This guide will use the modern, declarative approach with Home Manager and Flakes.

Part 1: Installation and Initial Setup

This section provides the definitive, step-by-step installation process based on our troubleshooting.

1. Prepare Your Steam Deck

Switch to Desktop Mode: Press the STEAM button, go to Power, and select Switch to Desktop.
Open Konsole: Click the application launcher icon in the bottom-left and open the Konsole terminal.
Set Administrator Password: This is required for the installer. In Konsole, type passwd and follow the prompts to set a password for your deck user.
Terminal window
```
passwd
```

2. Run the Determinate Systems Installer

This is the recommended installer for the Steam Deck. It correctly handles the immutable filesystem and enables modern features like Flakes by default.

Execute the Install Command: Copy and paste the entire command into Konsole and press Enter.

curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix | sh -s -- install

Follow the Prompts: The installer will ask for the password you just set. When it shows the installation plan and asks to proceed, type y and press Enter.

3. Finalize and Verify the Installation

IMPORTANT - Reboot: After the installer finishes, it’s crucial to reboot to ensure all system services are correctly loaded.
Terminal window
```
sudo reboot
```
Verify Installation: After rebooting, return to Desktop Mode, open Konsole, and run:
Terminal window
```
nix run nixpkgs#hello
```
If the command prints Hello, world!, your Nix installation is successful and ready.

Part 2: Declarative Environment with Home Manager & Flakes

Now we will set up the declarative environment. This is the core of the modern Nix workflow.

1. Create Your Configuration Directory

This folder will hold your Nix configuration files. Using Git to track changes is highly recommended.

mkdir -p ~/.config/home-manager
cd ~/.config/home-manager
git init

2. Create the flake.nix File

This file defines the inputs for your configuration, primarily the nixpkgs package set and home-manager itself.

Open a text editor: kate flake.nix

Paste the following content and save the file:

{
  description = "My Steam Deck's Home Manager Configuration";

  inputs = {
    nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
    home-manager = {
      url = "github:nix-community/home-manager";
      inputs.nixpkgs.follows = "nixpkgs";
    };
  };

  outputs = { self, nixpkgs, home-manager,... }: {
    homeConfigurations."deck" = home-manager.lib.homeManagerConfiguration {
      pkgs = nixpkgs.legacyPackages.x86_64-linux;
      modules = [./home.nix ];
    };
  };
}

3. Create the home.nix File

This is your main configuration file where you’ll list the packages you want.

Open a text editor: kate home.nix

Paste this starter configuration and save it:

{ config, pkgs,... }: {
  home.username = "deck";
  home.homeDirectory = "/home/deck";

  # This is important for ensuring configuration compatibility.
  home.stateVersion = "24.05";

  # Let Home Manager manage itself.
  programs.home-manager.enable = true;

  # The list of packages you want to install.
  home.packages = with pkgs; [
    # Add packages here, for example:
    neofetch
    btop
    git
  ];

  # This allows you to install software with non-free licenses, like Discord or VSCode.
  nixpkgs.config.allowUnfree = true;
}

4. Commit Your Initial Configuration

Flakes work with Git, so you must add your new files to be tracked.

git add flake.nix home.nix
git commit -m "Initial Home Manager configuration"

5. Activate Your Configuration

This command builds the environment you just defined and activates it. Run this from the ~/.config/nixpkgs directory.

nix run home-manager -- switch --flake .#deck

Part 3: Daily Workflow - Managing Your Software

Your setup is complete. From now on, managing your software is a simple, three-step process.

1. To Add or Remove a Package:

Open your configuration file: kate ~/.config/nixpkgs/home.nix
Add or remove the package name from the home.packages list.
Apply the changes by running this command from the ~/.config/nixpkgs directory:
Terminal window
```
home-manager switch --flake .#deck
```

2. To Update All Your Packages:

This is a two-step process that ensures perfect updates. [19, 13, 20, 21, 22, 23, 24]

Update the flake.lock file to the latest versions of your inputs:
Terminal window
```
nix flake update
```
Apply the updated configuration:
Terminal window
```
home-manager switch --flake .#deck
```

3. To Search for a Package:

To find the correct attribute name for a package to add to your home.nix, use the nix search command:

nix search nixpkgs <query>

For example: nix search nixpkgs vscode.

Part 4: Advanced Topics & System Integration

Making GUI Apps Appear in Desktop Mode

By default, GUI applications installed with Nix won’t show up in the application menu. To fix this declaratively, add the following line to your home.nix:

# In home.nix
targets.genericLinux.enable = true;

After adding this and running home-manager switch, your GUI apps will appear in the menu after a reboot.

Using Nix Applications in Game Mode

Steam’s Game Mode resets the environment, which breaks Nix applications because it can’t find the executables. To fix this, you must use a wrapper script in the game’s launch options.

In Steam (Desktop Mode is easiest), find the application you installed via Nix.
Right-click it, go to Properties… > General.
In the Launch Options field, enter the following, replacing your_app_command with the actual command for your application (e.g., heroic):
Terminal window
```
bash -c 'source /home/deck/.nix-profile/etc/profile.d/nix-daemon.sh && exec your_app_command'
```

Managing Dotfiles and Services

Home Manager can also manage your configuration files (dotfiles) and background services declaratively.

Dotfiles: Instead of manually symlinking files, you can manage them in home.nix. For example, to manage your Git configuration:
```
# In home.nix
programs.git = {
  enable = true;
  userName = "Your Name";
  userEmail = "[email protected]";
};
```
Services: To enable a background service like Syncthing, simply add:
```
# In home.nix
services.syncthing.enable = true;
```

Part 5: Understanding Configuration (`nix.conf`)

While you’ll mostly work in home.nix, it’s good to know about nix.conf. This file configures the Nix package manager itself. The system-wide configuration is at /etc/nix/nix.conf.

experimental-features = nix-command flakes: This is the most important setting, enabled by the Determinate installer, which turns on the modern Nix interface.
trusted-users: This lists users who can change restricted settings. If you see warnings about not being a “trusted user,” you can add your deck user to this list.
1. Open the file with sudo kate /etc/nix/nix.conf.
2. Add deck to the trusted-users line, e.g., trusted-users = root @wheel deck.
3. Save the file.
substituters: These are binary caches that provide pre-built packages, so Nix doesn’t have to build everything from source, which is much faster.
sandbox: This is a security and reproducibility feature. By default on Linux, Nix builds every package in an isolated “sandbox” environment.

Part 6: The Next Level & Uninstallation

Temporary Environments (nix-shell)

If you need a tool for a one-off task without permanently installing it, you can use nix-shell. This command downloads the package and drops you into a temporary shell where it’s available. When you exit, it’s gone.

# This gives you a temporary shell with the 'cowsay' command
nix-shell -p cowsay

Jovian-NixOS: Replacing SteamOS

For the ultimate power user, projects like Jovian-NixOS allow you to replace SteamOS entirely with a fully declarative NixOS system, giving you complete control over every aspect of your device while retaining a Steam Deck-like gaming experience.

Complete Uninstallation

If you decide to remove Nix:

Run the Uninstaller: The Determinate Systems installer provides a simple and thorough uninstaller.
Terminal window
```
/nix/nix-installer uninstall
```
Remove User Configurations: The uninstaller won’t touch your personal config files. You can remove them manually:
Terminal window
```
rm -rf ~/.config/nixpkgs
rm -rf ~/.local/state/home-manager
```
Reboot your Steam Deck.