Installing NixOS on Raspberry Pi 4

Nix is a tool that allows you to define your software environment from code. Nix has several components to it, and one of the most interesting to me is NixOS, which lets you use Nix tooling to define your entire OS configuration using plaintext files.

I only recently started experimenting with Nix, and there’s a huge amount to learn. One of the first things I tried to do was install NixOS on my Raspberry Pi, but my first several attempts failed. Every NixOS Pi tutorial I could find was either incomplete or out of date.

I present to you my complete and working guide to installing NixOS on a Raspberry Pi 4. I’m a newcomer to NixOS, so this guide is for Nix beginners, but I assume you have basic familiarity with Raspberry Pi and Linux.

Requirements 🔗︎

To follow this tutorial, you’ll need:

• A Raspberry Pi 4 with at least 2 GB of RAM
• A microSD card with at least 8 GB of storage
• A microSD writer
• A separate computer to flash the microSD card

Download the NixOS microSD image 🔗︎

To begin, download the NixOS microSD image from the link below:

• nixos-sd-image-23.11pre515819.8ecc900b2f69-aarch64-linux

You can find later images on Nix’s build server by checking the most recent build with a green check mark.

I recently attempted this process with a later build (nixos-image-sd-card-25.05beta741800.78886a72ed11, built on 2025-01-19), but the install failed. The later nixos-build step exhausted my Pi 4’s 2 GB of RAM.

Decompress the NixOS microSD image 🔗︎

The NixOS team compresses their microSD images with a compression format called Zstandard, an open-source format from Facebook.

To decompress the NixOS image, download the latest Zstandard release for your platform:

• Zstandard releases

Once you have both the Zstandard tool and the NixOS microSD image, decompress the .img.zst file with the following command:

Decompressing the Zstandard file should produce a file called nixos-sd-image-23.11pre515819.8ecc900b2f69-aarch64-linux.img.

Flash the NixOS microSD image 🔗︎

After you’ve decompressed the image, flash it to a microSD using your favorite microSD flashing utility.

When you flash the microSD, choose the .img file rather than the .img.zst file, as most flashing tools won’t understand the Zstandard format.

Option 1: balenaEtcher 🔗︎

If you don’t know which microSD flashing tool to use, I recommend balenaEtcher. It’s user-friendly and works on every major OS.

Option 2: caligula 🔗︎

balenaEtcher is not available on NixOS, so if you’re on NixOS, a good alternative is caligula:

caligula natively supports Zstandard file compression, so you don’t need to decompress the image first.

Insert the microSD card into your Pi 🔗︎

After you flash the microSD, insert it into the microSD slot of your Raspberry Pi:

Insert the flashed microSD card into your Pi’s microSD slot.

Connect a display and keyboard to your Pi 🔗︎

Most Raspberry Pi images offer a way to access the device over the network on the first boot. I haven’t found a way to do that with NixOS, so you’ll need to temporarily connect a keyboard and HDMI display to your Pi to see what’s happening.

NixOS has no fully-networked install, so you’ll need to connect a keyboard and HDMI display during the initial setup.

For this tutorial, I’m controlling my Pi with TinyPilot, a device I created for situations just like this.

You don’t need a TinyPilot for this tutorial, as you can follow along with a plain old keyboard and HDMI display.

Boot your NixOS system 🔗︎

It’s time for the moment of truth. Power on your Raspberry Pi.

If everything went well, you should see a boot sequence like the following:

The boot is complete when you see the NixOS command prompt:

If the boot failed, try updating your Pi’s bootloader to the latest available version and then trying again.

Enable SSH access (optional) 🔗︎

When working with Raspberry Pis, I find SSH much more convenient than typing on a separate keyboard.

There are two options for enabling SSH access on a fresh NixOS system.

Option 1: Add a password 🔗︎

On the NixOS system, you can assign a password to the default nixos user account by running the following command:

Once you’ve set a password, you can SSH into your NixOS system normally:

Option 2: Add an SSH key 🔗︎

You can also add your SSH public key as an authorized key on the system.

If you authenticate to GitHub with SSH keys, GitHub offers a convenient way to download your public SSH key to any device:

If you see an error that says certificate is not valid yet, it means that your Pi is still synchronizing its system time. Wait 60 seconds, and try the command again.

Once you’ve added your public SSH key to the NixOS system, you can SSH in like normal:

Write the NixOS configuration file 🔗︎

You’re now in NixOS!

There’s not much you can do yet because it’s a minimal NixOS environment with nothing installed.

To make your NixOS experience more interesting, install a desktop GUI and a few applications. To begin, download my example NixOS configuration file:

You can make changes to /etc/nixos/configuration.nix at this point using nano or vim. You might want to change the hostname, user, or password values at the top.

Don’t worry too much about perfecting the configuration file just yet. With NixOS, you can change your mind about any option at any time, and applying the change is as easy as editing the configuration file again.

When you’re happy with your configuration.nix file, run these commands to apply the configuration to your system and reboot:

When the reboot completes, you should see a screen that looks like this:

Your Pi is now running NixOS with a Gnome desktop environment!

If you used the default configuration.nix file above, your username is tempuser and your password is somepass.

Experimenting with NixOS 🔗︎

At this point, your NixOS system is up and running.

You’re free to explore NixOS as you wish, but I’ve included a couple of beginner experiments you can try on your new system.

Experiment 1: Change the desktop enviroment 🔗︎

The configuration.nix file above assumes that you want to use the Gnome desktop environment, but maybe you prefer a different one. There’s another desktop manager called Plasma that’s similar in design to Microsoft Windows.

To change your NixOS system to use Plasma instead of Gnome, open the your configuration.nix file in a text editor:

Find these lines in the file:

Replace them with these lines:

To apply the changes save the file, exit nano, and run these commands:

When you reboot, you should see a desktop like the following:

All it took to change your whole desktop environment was just a two-line change.

One of the most approachable Nix tools I’ve found is nix-shell. It lets you create software environments on the fly with any software packages you specify.

nix-shell doesn’t affect any other configuration on your system, so you’re free to try new tools without the risk of breaking anything else.

I sometimes run into projects I wrote a few years ago that depend on an older version of Node.js. I’ve tried tools like nvm to install Node versions side-by-side, but I always end up spending 20 minutes remembering how to use nvm and configure it correctly.

Even though nix-shell is a general purpose tool for installing packages, I find it more convenient even than language-specific dev tools like nvm.

Here’s how you can create a nix-shell environment with Node.js 18.x:

When you’re done with the environment, just hit Ctrl+D or type exit.

Here’s how you can do the same thing to create a Node.js 16.x environment:

Troubleshooting 🔗︎

Upgrade to the latest Pi bootloader 🔗︎

If you’re running into boot issues with NixOS, you may need to update your Pi’s bootloader and EEPROM.

Boot a recent build of Raspberry Pi OS (aka “Raspbian”), then run these command to install the latest bootloader:

To update the EEPROM, run these commands:

The Pi 4 devices I tested booted the NixOS 23.11 disk image out of the box, so the above steps weren’t necessary for me.

Appendix: Failed attempts 🔗︎

In creating this tutorial, I ran into a ton of paths that didn’t work. I’ve collected them here for the sake of saving others time retrying the same steps.

• Failed Attempts to Install NixOS on the Raspberry Pi 4

Thanks to Alex Groleau from the NixOS documentation team for his help with this guide and his work on the official NixOS Raspberry Pi tutorial.