NixOS Image Cross-Compilation Example

This repository contains the accompanying code for the Nixcademy blog post: Cross-Compiling NixOS images

📖 About this Repository

This project demonstrates how to set up a clean and scalable cross-compilation architecture for NixOS images using Nix Flakes.

Instead of hardcoding build targets, this repository shows how to:

• Strictly separate the system configuration from the build metadata.
• Use nixpkgs.buildPlatform and nixpkgs.hostPlatform to define cross-builds.
• Support cross-compilation on macOS (via the Linux builder).

It serves as the practical example for the fourth part of the Nixcademy series on building minimal, self-inflating, and auto-updating NixOS appliance images.

The article goes a step further to automatically generate the Cartesian product of all possible build and target platforms (e.g., building an aarch64 image from x86_64, or vice versa).

🔗 Read the Full Guide

For a detailed explanation of the logic behind extendModules, how to generalize cross-compilation functions, and how to set up the flake to build "anything from anywhere," please read the full article:

👉 Cross-Compiling NixOS images @ Nixcademy

🛠️ Usage

1. Explore Available Artifacts

You can see all available build targets (combinations of build platform and target image) by running:

nix flake show

You will see output similar to this, showing that you can build images for different architectures from your current system:

├───packages
│   ├───aarch64-linux
│   │   ├───image-aarch64
│   │   └───image-x86_64
│   └───x86_64-linux
│       ├───image-aarch64
│       └───image-x86_64

2. Build an Image

To cross-compile an AArch64 (ARM64) image while running on an x86_64 machine:

$ nix build .#image-aarch64

3. Inspect the Configuration

You can load the flake into the Nix REPL to inspect specific configuration values without building the entire image:

nix repl .

# Check the system version
nix-repl> nixosConfigurations.image.config.system.nixos.version

# Check where specific options are defined
nix-repl> :p nixosConfigurations.image.options.networking.hostName.definitionsWithLocations