Run NixOS guest VMs on a macOS or Linux host using Lima. nixos-lima is a Nix flake that generates Lima-compatible system images and provides a NixOS module for Lima boot-time and runtime support. The NixOS module runs in a Lima guest VM and configures the machine at boot-time using Lima configuration userdata and runs the lima-guestagent daemon as a systemd service.

By using the released system image and using the provided NixOS module, you can create your own custom configuration.

The design goals for nixos-lima are:

1. Nix flake that can build a bootable NixOS Lima-compatible image
2. Nix modules for the systemd services that initialize and configure the system
3. User customization of NixOS Lima instance is separate from initial image creation
4. The base image and Nix services module is generic and as reusable by others as possible

If you have comments or suggestions for the design or implementation, please open an Issue.

To quickly start a NixOS guest using Lima you don't need Nix installed on your host OS. Use the nixos.yaml template:

1. Install Lima (using Homebrew, Nix or another mechanism)
2. Create and start a new NixOS guest with limactl:

   limactl start github:nixos-lima

3. See NixOS Lima VM Config Sample for an example of how to maintain your custom NixOS system configuration (and optionally Home Manager) in your NixOS guest VM.

If you are curious about how the github:nixos-lima URL works, see GitHub Template URLs.

In your flake.nix, include nixos-lima as a flake input:

  inputs = {
    ...
    nixos-lima.url = "github:nixos-lima/nixos-lima/"
    ...
  };

In your system configuration, include:

  services.lima.enable = true;

For a complete, working example see: nixos-lima/nixos-lima-config-sample

You'll typically want to give the guest VM at least 8 GiB of memory. The nixos.yaml template contains the following:

memory: 8GiB

You can also specify guest memory allocation on the command line. For example to allocate 16 GiB use:

limactl start --memory 16 github:nixos-lima

There are at least three ways of managing the NixOS configuration of your image:

1. From inside the instance use git to check out a configuration repository and use nixos-rebuild.
2. From inside the instance, use nixos-rebuild on a configuration directory mounted from the host.
3. Push a configuration to the instance using the --target option of nixos-rebuild or using a remote deploy tool like deploy-rs.

For an example of (1) see nixos-lima/nixos-lima-config-sample.

If you want to build your own nixos-lima or contribute to this project, you can check out this repository and build the system image locally.

A working Nix installation capable of building Linux systems. This includes:

• Linux system with Nix installed
• Linux VM with Nix installed (e.g. under macOS)
• macOS system with linux-builder installed via Nix Darwin
• macOS system with nix-rosetta-builder

Flakes must be enabled.

This example is for aarch64, but you can replace aarch64 with x86_64 if you are on an x86_64 Linux or macOS system.

nix build .#packages.aarch64-linux.img --out-link result-aarch64

If you built the image on another system:

mkdir result-aarch64
# copy image to result-aarch64/nixos.qcow2

Once you've built or copied an image into the result-aarch64 directory, the nixos-result.yml template locates the images via a relative filesystem path:

limactl start --yes --name=nixos nixos-result.yaml

limactl shell nixos

If your Lima YAML file mounts your home directory (since limactl shell by default preserves the current directory) you can invoke nixos-rebuild inside the VM using a flake.nix in a directory on the host. The following command can be used on the host to rebuild NixOS in the guest from the flake.nix in the current directory:

limactl shell nixos -- nixos-rebuild boot --flake .#nixos-aarch64 --sudo
limactl restart nixos

This is based on kasuboski/nixos-lima and there were about a half-dozen forks of that repo, but none of them seemed to be making an effort to be generic/reusable, accept contributions, create documentation, etc. So I created this repo to try to create something that multiple developers can use and contribute to. (So now there are a half-dozen plus one projects 🤣 -- see xkcd "Standards")

• Lima discussion topic: NixOS guest? #430
• Lima issue: Template for nixOS #3688
• NixOS Dev Environment on Mac January, 24 2023 by Josh Kasuboski

• Forked from: kasuboski/nixos-lima
• Heavily inspired by: patryk4815/ctftools

The unmodified, upstream README is in README_upstream.md.

Fixes/patches from:

• unidevel/nixos-lima
• lima-vm/alpine-lima