Skip to main content
This guide covers installing Isabel’s Dotfiles on macOS using nix-darwin, which provides NixOS-like configuration for macOS systems.

​
Prerequisites

Before you begin, ensure you have:
  • macOS 10.15 (Catalina) or later
  • Administrator access
  • At least 10GB of free disk space
  • Xcode Command Line Tools installed
The macOS configuration uses Homebrew for apps that aren’t available in Nixpkgs. The setup is fully declarative using nix-homebrew.

​
Installation

1

Install Lix package manager

Install Lix, a modern Nix implementation:
curl -sSf -L https://install.lix.systems/lix | sh -s -- install
After installation, open a new terminal or source your shell profile:
source ~/.zshrc  # or ~/.bash_profile for bash
The installer will modify your shell profile and system configuration. Review the changes it makes.
2

Enter development shell

Use a Nix development shell to access required tools like git:
nix develop github:isabelroses/dotfiles
This provides a temporary environment with all necessary dependencies.
3

Clone the repository

Clone the dotfiles repository:
git clone https://github.com/isabelroses/dotfiles.git ~/.config/flake
cd ~/.config/flake
4

Choose your host

Check the available macOS configurations:
# View the tatsumaki configuration (example macOS host)
cat systems/tatsumaki/default.nix
The example configuration looks like:
{
  imports = [ ./users.nix ];

  garden = {
    profiles = {
      laptop.enable = true;
      graphical.enable = true;
      workstation.enable = true;
    };
  };
}
You can either:
  • Use tatsumaki as your host name
  • Create a new configuration for your Mac
5

Create your host configuration (optional)

If you want to create a custom configuration:
# Create a new host directory
mkdir -p systems/yourhostname

# Copy the example configuration
cp systems/tatsumaki/default.nix systems/yourhostname/
cp systems/tatsumaki/users.nix systems/yourhostname/

# Edit as needed
$EDITOR systems/yourhostname/default.nix
Add your host to systems/default.nix:
hosts = {
  # ... existing hosts ...
  
  yourhostname = {
    arch = "aarch64";  # or "x86_64" for Intel Macs
    class = "darwin";
  };
};
6

Provision the system

Run the provision command to apply the configuration:
just provision yourhostname
Or use the full command:
sudo nix run github:LnL7/nix-darwin -- switch --flake ~/.config/flake#yourhostname
The first run will take significant time as it downloads and builds all packages, including Homebrew casks.
7

Clean up temporary Lix install

The provision process installs Lix declaratively. Remove the imperative install:
sudo -i nix-env --uninstall lix

​
Homebrew integration

The configuration uses nix-homebrew to make Homebrew apps fully reproducible. The setup includes:

​
Configured casks

The default configuration installs these applications via Homebrew: 
casks = [
  "gimp"                    # Image editor
  "raycast"                 # App launcher and clipboard manager
  "discord"                 # Communication
  "ghostty"                 # Terminal emulator
  "helium-browser"          # Floating browser
  "jellyfin-media-player"   # Media player
];

​
Homebrew formulae

brews = [
  "mole"  # Network tunneling tool
];
All Homebrew packages are pinned to specific versions through nix-homebrew for reproducibility. This means brew update won’t work as expected - instead, update the flake.

​
Post-installation

​
Apply future changes

After modifying your configuration, apply changes using: 
# Using justfile
just switch

# Or manually
sudo darwin-rebuild switch --flake ~/.config/flake#yourhostname

​
Verify the installation

Check that the system is using your configuration: 
# Check darwin-rebuild version
darwin-rebuild --version

# View current generation
darwin-rebuild --list-generations

​
Using justfile commands

The repository includes macOS-specific just commands: 
# List all commands
just

# Apply configuration
just switch

# Test without switching
just test

# Update flake inputs
just update

​
Configuration options

​
System profiles

Available profiles you can enable:
  • graphical - GUI applications and desktop environment
  • laptop - Laptop-specific settings (battery, trackpad)
  • workstation - Development tools and productivity apps

​
Customizing Homebrew packages

Edit modules/darwin/brew/default.nix to add or remove applications: 
casks = [
  # Add your applications here
  "visual-studio-code"
  "firefox"
];

brews = [
  # Add command-line tools here
  "ffmpeg"
];

​
Hardware configuration

For macOS, hardware detection is automatic, but you can configure: 
garden.device = {
  keyboard = "us";  # Keyboard layout
  capabilities = {
    bluetooth = true;
  };
};

​
Troubleshooting

​
”experimental-features” error

If you get an error about experimental features: 
mkdir -p ~/.config/nix
echo "experimental-features = nix-command flakes" >> ~/.config/nix/nix.conf

​
Homebrew installation fails

If Homebrew packages fail to install: 
# Check Homebrew status
brew doctor

# View detailed logs
darwin-rebuild switch --flake ~/.config/flake#yourhostname --show-trace

​
Permission denied errors

Ensure you’re running darwin-rebuild with sudo: 
sudo darwin-rebuild switch --flake ~/.config/flake#yourhostname

​
Rolling back changes

If something breaks, roll back to a previous generation: 
# List generations
darwin-rebuild --list-generations

# Roll back to previous
sudo darwin-rebuild rollback

# Switch to specific generation
sudo darwin-rebuild switch --rollback --generation 42

​
Mac App Store apps

Some apps require manual installation from the App Store first: 
masApps = {
  "Xcode" = 497799835;
};
Install the app manually once, then add it to the configuration.

​
Architecture differences

​
Apple Silicon (M1/M2/M3)

For Apple Silicon Macs, set: 
arch = "aarch64";

​
Intel Macs

For Intel Macs, set: 
arch = "x86_64";

​
Next steps

Configuration guide

Learn how to customize your setup

Modules reference

Explore available modules

Build docs developers (and LLMs) love

Get started for freeTalk to us