Nix macOS Starter

A beginner-friendly Nix configuration for macOS using flakes, nix-darwin, Home Manager, and Mise.

About

A clean, well-documented starting point for managing your macOS system declaratively with Nix. Includes sensible defaults for development tools, shell configuration, and system settings.

Author: Ben Gubler

Prerequisites

1. Install Nix using the Determinate Systems installer (download the graphical installer for macOS). After installation, restart your terminal.

Note: Homebrew is managed declaratively via nix-homebrew - if you already have it installed, it will auto-migrate. Otherwise, it's installed automatically.

Quick Start

1. Clone and Configure

# Clone the repository
git clone https://github.com/nebrelbug/nix-macos-starter ~/.config/nix
cd ~/.config/nix

2. Customize Your Configuration

For Intel Mac Users: Change the system architecture in flake.nix from "aarch64-darwin" to "x86_64-darwin" on line 28.

Replace all placeholders:

• flake.nix: YOUR_USERNAME (this sets the username for the entire system)
• home/git.nix: YOUR_NAME, YOUR_EMAIL

3. Apply the Configuration

# Build and switch to the configuration
darwin-rebuild switch --flake .#my-macbook

# Or use the alias after initial setup
nix-switch

What's Included

Development Tools: mise for Node.js/Python/Rust/etc., Zsh with Starship prompt, essential CLI tools (curl, vim, tmux, htop, tree, ripgrep, gh, zoxide), code quality tools (nil, biome, nixfmt-rfc-style)

GUI Applications: Cursor, Ghostty, VS Code, Zed, Raycast, CleanShot, HiddenBar, BetterDisplay, Discord, Slack, 1Password, Brave Browser, Obsidian, Spotify

System Configuration: Git setup, macOS optimizations (Finder, Touch ID sudo), Nix settings (flakes, garbage collection), declarative Homebrew management

Project Structure

nix-macos-starter/
├── flake.nix                    # Main flake configuration and inputs
├── darwin/
│   ├── default.nix              # Core macOS system configuration
│   ├── settings.nix             # macOS UI/UX preferences and defaults
│   └── homebrew.nix             # GUI applications via Homebrew
├── home/
│   ├── default.nix              # Home Manager configuration entry point
│   ├── packages.nix             # Package declarations and mise setup
│   ├── git.nix                  # Git configuration
│   ├── shell.nix                # Shell configuration
│   └── mise.nix                 # Development runtime management
└── hosts/
    └── my-macbook/
        ├── configuration.nix    # Host-specific packages and settings
        └── shell-functions.sh   # Custom shell scripts

Customization

Add CLI Tools: Edit home/packages.nix packages array
Add GUI Apps: Edit darwin/homebrew.nix casks array
Add Development Tools: Add ${pkgs.mise}/bin/mise use --global tool@version to home/mise.nix activation script
Host-Specific Config: Use hosts/my-macbook/configuration.nix for machine-specific packages/apps and custom-scripts.sh for shell scripts

Troubleshooting

"Command not found": Restart terminal
Permission denied: Use sudo darwin-rebuild switch --flake .#my-macbook
Homebrew apps not installing: nix-homebrew handles this automatically; ensure /opt/homebrew/bin in PATH
Git config not applying: Replace all YOUR_* placeholders, re-run darwin-rebuild

Need help? Check Nix manual, nix-darwin docs, Home Manager options

Credits

• Ethan Niser for his config repo which I used as a reference for this project.
• David Haupt's excellent tutorial series which (although slightly outdated) helped me understand the basics of Nix.