NixOS on macOS Guide

This comprehensive guide covers running and testing NixOS configurations on macOS using UTM, QEMU, and other virtualization solutions.

Table of Contents

  1. Overview
  2. Prerequisites
  3. Quick Start
  4. Virtual Machine Configurations
  5. ISO Installers
  6. UTM Setup Guide
  7. Performance Optimization
  8. Architecture Considerations
  9. Development Workflow
  10. Troubleshooting
  11. Advanced Usage

Overview

This template provides comprehensive macOS support including:

NixOS Virtualization:

Native macOS Management:

Supported Configurations

Virtual Machines:

Architecture Support:

ISO Installers:

nix-darwin Configurations:

Prerequisites

System Requirements

Hardware:

Software:

Installing Prerequisites

  1. Install Nix:

    curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix | sh -s -- install
  2. Install UTM (recommended):

  3. Enable Nix Flakes (if not enabled):

    echo 'experimental-features = nix-command flakes' >> ~/.config/nix/nix.conf

Quick Start

Option 1: Native macOS Management (nix-darwin)

For managing your Mac directly with Nix:

# Clone the template
git clone https://github.com/yourusername/nixos-template
cd nixos-template

# Install nix-darwin
./scripts/install-nix-darwin.sh

Option 2: NixOS Virtualization (Testing)

For testing NixOS configurations in VMs:

# Clone the template
git clone https://github.com/yourusername/nixos-template
cd nixos-template

# Run the interactive macOS script
./scripts/try-nixos-macos.sh

Option 3: Direct Commands

# Build desktop VM (auto-detects your Mac's architecture)
just build-macos-vm desktop

# Run the VM
./result/bin/run-desktop-macos-vm

# Login: nixos/nixos

Option 4: Using Just Commands

# List all macOS options
just list-macos

# Build specific configurations
just build-macos-vm laptop aarch64    # For Apple Silicon
just build-macos-vm server x86_64     # For Intel Mac
just build-macos-iso desktop          # Build installer ISO

# Test without building
just test-macos desktop aarch64

# Get comprehensive help
just macos-help

nix-darwin Native macOS Management

What is nix-darwin?

nix-darwin brings the power of NixOS configuration management to macOS. Instead of manually installing and configuring software, you declare your entire system configuration in code.

Benefits of nix-darwin

Reproducible Systems:

Rollback Capability:

Integration:

nix-darwin Configurations

Desktop Configuration

Target: Primary development machines, iMacs, Mac Studios Features:

Laptop Configuration

Target: MacBooks, mobile development Features:

Server Configuration

Target: Headless development, CI/CD, Mac minis Features:

Installation

Quick Installation:

git clone https://github.com/yourusername/nixos-template
cd nixos-template
./scripts/install-nix-darwin.sh

Manual Installation:

# Clone template
git clone https://github.com/yourusername/nixos-template ~/.config/nix-darwin
cd ~/.config/nix-darwin

# Install for Apple Silicon
nix run nix-darwin -- switch --flake .#darwin-desktop

# Install for Intel Mac
nix run nix-darwin -- switch --flake .#darwin-desktop-intel

Usage

System Management:

# Apply configuration changes
darwin-rebuild switch --flake ~/.config/nix-darwin

# Update system and packages
darwin-update

# Show system information
darwin-info

# List previous generations
darwin-rebuild --list-generations

# Rollback to previous generation
darwin-rebuild --rollback

Customization: Edit configuration files in ~/.config/nix-darwin/hosts/darwin-*/:

Example Changes:

# Add a new package
environment.systemPackages = with pkgs; [
  # existing packages...
  neofetch  # Add this line
];

# Change system preferences
system.defaults.dock.tilesize = 64;  # Larger dock icons

# Add Homebrew application
homebrew.casks = [
  # existing apps...
  "spotify"  # Add this line
];

Then apply changes:

darwin-rebuild switch --flake ~/.config/nix-darwin

For More Information

See the complete nix-darwin Guide for:

Virtual Machine Configurations

Desktop VM

Purpose: Full desktop environment for testing and development

Specifications:

Features:

Build Commands:

# Apple Silicon
just build-macos-vm desktop aarch64

# Intel Mac
just build-macos-vm desktop x86_64

# Or use architecture detection
just build-macos-vm desktop

Laptop VM

Purpose: Laptop-specific features testing and mobile computing simulation

Specifications:

Features:

Unique Utilities:

Server VM

Purpose: Headless server development and testing

Specifications:

Features:

Services:

Management Commands:

ISO Installers

Desktop ISO

Purpose: Graphical NixOS installer with desktop environment

Features:

Usage:

  1. Build the ISO: just build-macos-iso desktop
  2. Import into UTM as CD/DVD
  3. Create new VM with appropriate settings
  4. Boot from ISO and follow installer

Installation Scripts:

Minimal ISO

Purpose: Lightweight server installer

Features:

Usage:

  1. Build the ISO: just build-macos-iso minimal
  2. Boot in UTM with minimal resources
  3. SSH access: ssh nixos@<vm-ip>
  4. Use installation scripts or manual process

Installation Scripts:

UTM Setup Guide

Creating a New VM in UTM

  1. Download UTM:
    • Mac App Store (easiest)
    • GitHub releases (latest features)
  2. Create New VM:
    • Click “Create a New Virtual Machine”
    • Choose “Virtualize” (Apple Silicon) or “Emulate” (Intel/compatibility)
  3. Operating System:
    • Select “Linux”
    • Choose architecture: ARM64 (M1/M2/M3) or x86_64 (Intel)

  4. Configuration:

    Architecture: ARM64 (Apple Silicon) or x86_64 (Intel)
System:      QEMU 7.0+ ARM/x86 Virtual Machine
Memory:      4096 MB (desktop), 2048 MB (server)
Storage:     20 GB+ (varies by use case)
  5. Boot Configuration:
    • Enable UEFI Boot
    • Add CD/DVD drive for ISOs
    • Network: Shared Network (NAT)

Importing Pre-built VMs

  1. Build VM with this template:

    just build-macos-vm desktop
  2. Extract QEMU command:
    • The built VM includes a run script
    • Copy QEMU parameters for UTM
  3. Create UTM VM:
    • Use “Custom” configuration
    • Apply extracted parameters
    • Import disk image

UTM Performance Settings

Apple Silicon Optimization:

Intel Mac Optimization:

Performance Optimization

Architecture-Specific Optimizations

Apple Silicon (M1/M2/M3):

Intel Macs:

VM Resource Allocation

Desktop VM:

Laptop VM:

Server VM:

Host System Optimization

macOS Settings:

Storage Optimization:

Architecture Considerations

Apple Silicon (aarch64)

Advantages:

Considerations:

Recommended Usage:

Intel Macs (x86_64)

Advantages:

Considerations:

Recommended Usage:

Cross-Architecture Support

This template supports both architectures with:

Development Workflow

Typical Development Process

  1. Start with VM Development:

    # Build and test in VM first
just build-macos-vm desktop
./result/bin/run-desktop-macos-vm

  2. Iterate on Configurations:

    # Edit configurations
vim hosts/macos-vms/desktop-macos.nix

# Rebuild and test
just build-macos-vm desktop

  3. Create Custom ISOs:

    # Build installer with your configs
just build-macos-iso desktop

  4. Deploy to Real Hardware:

    • Use ISOs to install on physical machines
    • Apply tested configurations
    • Minimal migration needed

Integration with macOS Development

File Sharing:

Tool Integration:

Version Control:

Troubleshooting

Common Issues

VM Won’t Boot:

Slow Performance:

Network Issues:

Graphics Problems:

Build Failures:

Architecture-Specific Issues

Apple Silicon:

Intel Mac:

Debug Commands

# Check system information
system -version
uname -a

# Monitor VM resources
htop
iotop

# Network diagnostics
ping google.com
nslookup nixos.org
netstat -rn

# Nix debugging
nix --version
nix show-config

Getting Help

Template-Specific:

Community Resources:

Advanced Usage

Custom VM Configurations

Creating Custom VMs:

  1. Copy existing configuration:

    cp -r hosts/macos-vms/desktop-macos hosts/my-custom-vm

  2. Customize configuration:

    vim hosts/my-custom-vm/configuration.nix

  3. Add to flake.nix:

    my-custom-vm = mkSystem {
  hostname = "my-custom-vm";
  system = "aarch64-linux";
  extraModules = [ templateConfig ];
};

  4. Build and test:

    nix build .#nixosConfigurations.my-custom-vm.config.system.build.vm

Cross-Compilation

Building for Different Architectures:

# Build aarch64 on Intel Mac
nix build .#nixosConfigurations.desktop-macos.config.system.build.vm --system aarch64-linux

# Build x86_64 on Apple Silicon
nix build .#nixosConfigurations.desktop-macos-intel.config.system.build.vm --system x86_64-linux

Remote Development

SSH into VMs:

# Start VM with port forwarding
ssh -p 2222 nixos@localhost

# Or use direct VM IP
ssh nixos@192.168.64.xxx

VS Code Remote Development:

  1. Install “Remote - SSH” extension
  2. Connect to VM via SSH
  3. Develop directly in VM environment

Container Development

Using Podman in VMs:

# In server VM
podman run -d -p 8080:80 nginx
podman build -t myapp .
podman-compose up

Docker Alternative:

Shared Folder Configuration

UTM Shared Folders:

  1. Enable in UTM VM settings

  2. Mount in NixOS:

    fileSystems."/mnt/shared" = {
  device = "share";
  fsType = "9p";
  options = [ "trans=virtio" "version=9p2000.L" ];
};

Automation and CI/CD

Automated Testing:

# Test all macOS configurations
just test-all-macos

# Build verification
just build-all-macos

Integration with CI/CD:

Resources

Documentation

Community

Apple-Specific Resources

Learning Resources

This guide provides comprehensive coverage of running NixOS on macOS. For additional help, run just macos-help or refer to the template documentation.