My personal notes and memos about playing with NixOS on a Raspberry PI
Branch: master
Clone or download
zupo irl.nix cleanup
Since this is a RPi 3 B and not a RPi 3 B+, the additional kernel
hacks are not neede.
Latest commit 224ae94 Feb 5, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information.
.kodi/userdata/keymaps kodi keymap for OSMC remote v1 Dec 25, 2018
features templates for secrets Dec 26, 2018
secrets Be nicer about secrets files Feb 5, 2019
.gitignore Let's make this into a tutorial Dec 26, 2018 todos Jan 3, 2019
irl.nix irl.nix cleanup Feb 5, 2019
minimal.nix Greatly simplify things Dec 28, 2018
minimal.output Let's make this into a tutorial Dec 26, 2018
tv.nix todos Jan 3, 2019

Getting started with NixOS on Raspberry Pi 3 Model B+

This is a step-by-step guide on diving into NixOS by installing and using it on a Raspberry Pi 3 Model B+.

The official documentation on running NixOS on ARM, and more specifically, on a Raspberry Pi is quite good. But it has to cover a lot of edge cases and old revisions, plus it assumes some prior experience with NixOS. I had none. I did however have the luxury of @domenkozar hand-holding me through instructions so that I could build my first NixOS install. But not everyone has the same privilege! And for those of you, this guide tries to provide enough hand-holding so that anyone with some general Linux experience is able to follow.

To make the guide even easier to follow, it is focused only on a single board: the Raspberry Pi 3 Model B+.

The end game is a robust and future-proof Media Center running on a Raspberry Pi 3.


  • The development machine that you will use to work through this guide, is a MacBook or a Linux machine you know well (and you can Google Linux alternatives for MacOS apps)
  • The Raspberry Pi will use wired ethernet, and will get the IP via DHCP.
  • The Raspberry Pi is connected to an HDMI display.
  • You have a somewhat decent Internet connection.

Minimal install

First, we'll do a minimal install of NixOS on your Raspberry Pi. Adding extra software on top of the minimal install is very easy and we'll do it later.

Installing NixOs on the SD card

  1. Go to and find the line that contains nixos:release-18.09-aarch64. 18.09 is the current stable version of NixOs.
  2. Click on the nixos.sd_image.aarch64-linux part of the line to see the latest builds. Click on the most recent one that has passed successfully (green checkmark).
  3. Click on the link in the File sd-image line. Mine was nixos-sd-image-18.09beta1819.76aafbf4bf4-aarch64-linux.img and the URL was
  4. Use Etcher to flash the image onto your SD Card. Please use 8GB or bigger card.

First boot

  1. Put the NixOs SD card into the Pi's SD cart slot and turn it on. If all goes well, you should be dropped into a root shell.

  2. Copy over the contents of minimal.nix into /etc/nixos/configuration.nix.

    [root@nixos:~]# curl > /etc/nixos/configuration.nix
  3. And we're ready to build our minimal configuration.

    [root@nixos:~]# nixos-rebuild switch
    building Nix...
    building the system configuration...
    these derivations will be built:

    The first build takes about 10 minutes, consequent ones are faster.

  4. Reboot to see it if works.


At this point, your Raspberry Pi should boot into the minimal NixOS configuration defined in minimal.nix. Let's do some cleanup before we continue.

[root@nixos:~]# nix-collect-garbage -d  # remove old pre-built configuration and all of its dependencies
[root@nixos:~]# nixos-rebuild switch  # remove old boot entries
[root@nixos:~]# reboot  # to be on the safe side

Ready for features

Now that you have the base NixOS install running on your Raspberry PI you can browse .nix files in the features/ directory, copy their configuration into your /etc/nixos/configuration.nix and re-run nixos-rebuild switch.

Let's try one for practice: the home theater software Kodi.

  1. Add the following to /etc/nixos/configuration.nix:

    # Enable X11 windowing system
    services.xserver.enable = true;
    services.xserver.videoDrivers = [ "modesetting" ];
    # Enable Kodi
    services.xserver.desktopManager.kodi.enable = true;
    # Enable slim autologin
    services.xserver.displayManager.lightdm.enable = true;
    services.xserver.displayManager.lightdm.autoLogin.enable = true;
    services.xserver.displayManager.lightdm.autoLogin.user = "kodi";
    # Define a user account
    users.extraUsers.kodi.isNormalUser = true;
  2. Run nixos-rebuild switch and reboot when it's done.

Where to go from here?

  • Check out the fully-fledged tv.nix configuration I use on my Raspberry Pi. In there you have static IP configuration, automounting of NAS, importing from other .nix files and more.

  • I really liked the one hour, hands-on tutorial when starting out. I got the basic knowledge needed to follow the official NixOS documentation.

  • Keep the cheatsheet handy.


  • @domenkozar for not shying away from my endless harassment on IM when I got stuck. Which was often. It truly is a testament to NixOS' design that Domen was able to debug and fix my problems from 2500 kilometers away. And that's only because all "system state" is in the configuration.nix file and not sprinkled among tens of opaque locations around the filesystem.
  • The authors of NixOS on ARM which is a treasure-trove of tips & tricks.
  • Other folks on the #nixos-aarch64 IRC channel for support and insights.