notes/pinephone-nixos-getting-started.md -rw-r--r-- 4.1 KiB
4bb2ed0aTom Fitzhenry Link to https://nixos.wiki/wiki/PinePhone 10 months ago

#NixOS on Pinephone

Here's an easy way for NixOS users to install a graphical NixOS on their Pinephone.


  • Pinephone
  • 8GB microSD card.
  • A NixOS machine to build the microSD card image.
  • A way to plug a microSD card into your NixOS machine


tl;dr Set up your machine to build aarch64 images, then get cache.nixos.org to do all the heavy lifting.

Set up your machine to run aarch64 binaries via binfmt by adding the following to your /etc/nixos/configuration (and applying it):

boot.binfmt.emulatedSystems = [ "aarch64-linux" ];

Don't worry, you're not actually to compile any binaries via this emulation: that'd be too slow. To avoid building binaries, you'll rely on cache.nixos.org.[^moustache]

To rely on cache.nixos.org, you'll need to know a recent pair of nixpkgs and mobile-nixos commits that have built successfully.

At the time of writing, a recent example is:

  • mobile-nixos at 85557dca93ae574eaa7dc7b1877edf681a280d35
  • nixpkgs at 7e567a3d092b7de69cdf5deaeb8d9526de230916

Now let's checkout both of those. It's important to do both, since they're built as a whole, and thus the caching will rely on that.

$ mkdir $HOME/pinephone
$ cd $HOME/pinephone
$ git clone https://github.com/NixOS/mobile-nixos
$ (cd mobile-nixos; git checkout 85557dca93ae574eaa7dc7b1877edf681a280d35)
$ git clone https://github.com/NixOS/nixpkgs
$ (cd nixpkgs; git checkout 7e567a3d092b7de69cdf5deaeb8d9526de230916)

#Let's build an image

We now have to tell mobile-nixos what programs image should contain, which we do via local.nix.

Create local.nix in your mobile-nixos checkout as follows:

{ lib, pkgs, ... }:

  imports = [
  nixpkgs.system = "aarch64-linux";
  environment.systemPackages = [
	# ... etc

examples/demo is a mobile configuration that uses XFCE. XFCE might not be your favourite, but it works so just pick it for now. You can customise later.

You're ready to build!

$ export NIX_PATH="nixpkgs=$HOME/pinephone/nixpkgs"
$ cd mobile-nixos/
$ nix-build  --argstr device pine64-pinephone -A build.disk-image
[... download lots from cache.nixos.org ...]

That should take a few minutes.

Copy the disk image to your microSD card (don't worry about partitions, it's all sorted).

$ dd if=result of=/dev/mmcblkX bs=8M oflag=sync,direct status=progress

#Boot the image to NixOS!

Plug the microSD card into your Pinephone, and turn it on.

You should see a NixOS-branded splash screen within 10s, and an XFCE desktop within 30-60s.

#Known issues

#Next steps

You're now bootstrapped onto a NixOS machine with aarch64, so you have a few options for exploration.


[^moustache]: I don't know why emulating aarch64 is needed, since Hydra does all the heavy lifting. Perhaps nixpkgs evaluation itself is arch-dependent? I don't know. I don't question the door policy, I just put on the fake moustache and walk in. 🥸