Cross-Platform Nix Configuration

A modular Nix configuration that works on both macOS (via nix-darwin) and Linux (NixOS), with maximum config sharing through home-manager.

Structure

├── flake.nix                    # Main flake configuration
├── common.nix                   # Shared system-level config (NixOS & nix-darwin)
│
├── darwin/                      # macOS system configuration
│   └── configuration.nix
│
├── nixos/                       # NixOS system configuration
│   ├── configuration.nix
│   └── hardware-configuration.nix
│
├── home-manager/                # User environment (shared across platforms)
│   ├── home.nix                 # Main home-manager config
│   ├── common.nix               # Base configuration
│   ├── development.nix          # Development tools
│   ├── shell.nix                # Shell configuration
│   ├── terminal.nix             # Terminal apps & utilities
│   ├── linux.nix                # Linux-specific overrides
│   └── darwin.nix               # macOS-specific overrides
│
├── modules/
│   ├── home-manager/            # Shared home-manager modules
│   ├── nixos/                   # NixOS-specific modules
│   └── darwin/                  # nix-darwin-specific modules
│
├── overlays/                    # Package overlays
│   └── default.nix
│
└── pkgs/                        # Custom packages
    └── default.nix

Getting Started

Prerequisites

On macOS:

1. Install Nix: sh <(curl -L https://nixos.org/nix/install)
2. Enable flakes by adding to ~/.config/nix/nix.conf:

   experimental-features = nix-command flakes
   

On NixOS: Flakes should be enabled via this configuration.

Configuration Steps

1. Update your username and hostname:

   • In flake.nix: Replace your-username and your-hostname in the configurations
   • In home-manager/home.nix: Update the username
   • In darwin/configuration.nix or nixos/configuration.nix: Update hostname and user settings

2. Set your architecture (macOS):

   • In darwin/configuration.nix, set nixpkgs.hostPlatform to either:
     • "aarch64-darwin" (Apple Silicon)
     • "x86_64-darwin" (Intel)

3. Configure Git identity (optional):

   • In home-manager/development.nix, uncomment and set:

     userName = "Your Name";
     userEmail = "your.email@example.com";
     

Building & Activating

On macOS (first time):

# Build the darwin configuration
nix build .#darwinConfigurations.your-hostname.system

# Activate it
./result/sw/bin/darwin-rebuild switch --flake .#your-hostname

On macOS (subsequent builds):

darwin-rebuild switch --flake .#your-hostname

On NixOS:

sudo nixos-rebuild switch --flake .#your-hostname

Standalone home-manager (if not using system integration):

home-manager switch --flake .#your-username@your-hostname

Key Features

Platform-Aware Configuration

The configuration automatically detects the platform using pkgs.stdenv.isDarwin and pkgs.stdenv.isLinux:

• Home directory: Automatically uses /Users/ on macOS, /home/ on Linux
• Platform-specific packages and services are conditionally enabled
• Shared configuration in common.nix for consistent experience

Modular Home-Manager

Your user environment is split into logical modules:

• common.nix: Basic tools everyone needs (git, ripgrep, etc.)
• development.nix: Development tools (languages, IDEs, etc.)
• shell.nix: Shell configuration (bash, zsh, fish, starship)
• terminal.nix: Terminal applications (tmux, neovim, alacritty)
• linux.nix: Linux-specific GUI apps and services
• darwin.nix: macOS-specific apps and integrations

Shared System Configuration

common.nix is imported by both NixOS and nix-darwin configurations, providing:

• Unified Nix settings (flakes, garbage collection, etc.)
• Shared package overlays
• Consistent nixpkgs configuration

Easy to Extend

• Add new home-manager modules in modules/home-manager/
• Add platform-specific modules in modules/nixos/ or modules/darwin/
• Add custom packages in pkgs/
• Add overlays in overlays/

Customization Tips

Adding Packages

User packages (home-manager): Add to the appropriate module:

• home-manager/common.nix for shared packages
• home-manager/linux.nix for Linux-only
• home-manager/darwin.nix for macOS-only
• home-manager/development.nix for dev tools

System packages: Add to common.nix for shared system packages, or to the platform-specific config.

Enabling Programs

Most programs can be enabled via home-manager:

programs.firefox.enable = true;
programs.vscode.enable = true;

Check home-manager options for available programs.

Multiple Machines

Add more configurations in flake.nix:

darwinConfigurations = {
  macbook = darwin.lib.darwinSystem { ... };
  mac-mini = darwin.lib.darwinSystem { ... };
};

nixosConfigurations = {
  desktop = nixpkgs.lib.nixosSystem { ... };
  laptop = nixpkgs.lib.nixosSystem { ... };
};

macOS System Defaults

The darwin configuration includes sensible defaults for macOS. Customize in darwin/configuration.nix:

• Dock behavior
• Finder settings
• Keyboard settings
• Global domain defaults

Maintenance

Update flake inputs:

nix flake update

Garbage collect old generations:

# This happens automatically every 7 days, but you can run manually:
nix-collect-garbage -d

# On NixOS:
sudo nix-collect-garbage -d

View generations:

# On macOS:
darwin-rebuild --list-generations

# On NixOS:
sudo nix-env --list-generations --profile /nix/var/nix/profiles/system

Rollback to previous generation:

# On macOS:
darwin-rebuild --rollback

# On NixOS:
sudo nixos-rebuild --rollback

Resources

• Nix Documentation
• NixOS Options Search
• Home Manager Options
• nix-darwin Options
• Nix Language Basics

Troubleshooting

"error: experimental Nix feature 'flakes' is disabled"

• Enable flakes in your nix configuration

Build fails on macOS

• Ensure nix-darwin is properly installed
• Check that your architecture is set correctly in darwin/configuration.nix

Home manager conflicts

• If you have existing dotfiles, back them up before applying home-manager
• Use home-manager switch --backup-extension .backup to preserve existing files

"collision between" errors

• Usually means packages are providing the same files
• Check for duplicate package installations in system vs home-manager

Contributing

Feel free to customize this configuration to your needs! The modular structure makes it easy to:

• Add new feature modules
• Share modules between machines
• Contribute modules back to the community