Skip to main content
Darwin modules configure macOS systems using nix-darwin. They provide declarative configuration for system preferences, Homebrew packages, hardware settings, and macOS-specific features.

​
What Darwin modules provide

These modules adapt the NixOS configuration framework to work on macOS, handling the differences between Linux and Darwin while maintaining a consistent interface.

System preferences

Dock, Finder, keyboard, trackpad, and other macOS settings

Homebrew integration

Declarative Homebrew package and cask management

Hardware settings

Keyboard layouts, trackpad configuration, and device preferences

Security

Firewall, FileVault, and security policies

​
Module categories

​
preferences/

macOS system preferences configured declaratively.
Control the macOS Dock appearance and behavior.
modules/darwin/preferences/dock.nix
{
  system.defaults.dock = {
    autohide = true;
    autohide-delay = 0.0;
    autohide-time-modifier = 1.0;

    orientation = "bottom";
    tilesize = 1;

    # Disable recent apps and spaces
    show-recents = false;
    mru-spaces = false;

    # Hot corners (1 = Disabled)
    wvous-tl-corner = 1;
    wvous-tr-corner = 1;
    wvous-bl-corner = 1;
    wvous-br-corner = 1;
  };
}
Hot corner options:
  • 1 - Disabled
  • 2 - Mission Control
  • 3 - Application Windows
  • 4 - Desktop
  • 5 - Start Screen Saver
  • 10 - Put Display to Sleep
  • 11 - Launchpad
  • 13 - Lock Screen
Configure Finder file browser settings.Includes:
  • Default view style (icon, list, column, gallery)
  • Show/hide hidden files
  • Show file extensions
  • Search scope defaults
  • Path bar and status bar visibility
Configure the menu bar clock display format and options.
Login window appearance and behavior, including:
  • Auto-login settings
  • Guest account configuration
  • Login window text
Regional settings for:
  • Temperature units (Celsius/Fahrenheit)
  • Measurement system (metric/imperial)
Screenshot location, format, and default image viewers.
Sound effects, volume, and audio device configuration.
Miscellaneous system preferences that don’t fit other categories.

​
hardware/

Hardware device configuration.
Keyboard layout, modifier keys, and input settings.Configure:
  • Key repeat rate and delay
  • Modifier key remapping (Caps Lock to Control, etc.)
  • Keyboard shortcuts
  • Input sources and layouts
Trackpad gestures and sensitivity.Configure:
  • Tap to click
  • Natural scrolling direction
  • Tracking speed
  • Multi-finger gestures
  • Force Click behavior

​
brew/

Homebrew package manager integration.
Declaratively manage Homebrew packages, casks, and taps.The brew/ modules provide:
  • Homebrew installation and updates
  • Package installation from Homebrew
  • Cask installation for GUI applications
  • Tap management for third-party repositories
  • Environment variable configuration
Example usage:
{
  homebrew = {
    enable = true;
    
    brews = [
      "imagemagick"
      "ffmpeg"
    ];
    
    casks = [
      "discord"
      "spotify"
    ];
    
    taps = [
      "homebrew/cask-fonts"
    ];
  };
}
Sets up environment variables so Homebrew packages are available in your PATH.Automatically configures:
  • /opt/homebrew/bin for Apple Silicon
  • /usr/local/bin for Intel Macs
  • Shell integration for bash, zsh, fish

​
security/

Security settings for macOS.
  • Firewall configuration
  • FileVault encryption
  • Gatekeeper settings
  • Privacy controls

​
Top-level modules

These modules live directly in the darwin/ directory:
Darwin-specific Nix daemon settings, including:
  • Build users and groups
  • Daemon socket configuration
  • Auto-optimization settings
Disables man page generation to save disk space and build time.
{
  documentation.enable = false;
}
Packages that should be available system-wide to all users.
Sets the path to the nix-darwin configuration for system management.
Imports external modules that don’t have a designated place in the structure.
Compatibility layer for options that need refactoring upstream.Provides backwards compatibility while the framework evolves.

​
Usage example

Here’s a complete example of configuring a macOS system:
darwin-configuration.nix
{ inputs, pkgs, ... }:
{
  # Import the framework
  imports = [ inputs.garden.darwinModules.default ];

  # System preferences
  system.defaults = {
    dock = {
      autohide = true;
      orientation = "left";
      show-recents = false;
    };
    
    finder = {
      AppleShowAllExtensions = true;
      ShowPathbar = true;
    };
  };

  # Homebrew packages
  homebrew = {
    enable = true;
    
    brews = [ "mas" ];
    
    casks = [
      "raycast"
      "arc"
    ];
  };

  # System packages
  garden.packages = with pkgs; {
    inherit git vim curl;
  };

  # Configure Nix
  nix.settings = {
    experimental-features = [ "nix-command" "flakes" ];
  };
}

​
Key features

​
Declarative system preferences

All macOS system preferences are declared in Nix configuration files. When you rebuild your system, preferences are automatically applied. 
darwin-rebuild switch --flake .

​
Homebrew integration

Homebrew packages are declared alongside Nix packages, giving you access to both ecosystems. The framework handles installation and updates.

​
Consistent with NixOS

Darwin modules mirror the structure and naming of NixOS modules where possible, making it easy to maintain configurations for both platforms.

​
Base module inheritance

Darwin automatically imports base modules, sharing common configuration between macOS and NixOS systems.

​
Differences from NixOS

macOS limitations mean some NixOS features aren’t available:
  • No systemd (uses launchd instead)
  • Different user management system
  • Limited kernel configuration
  • Some services require Homebrew versions
The framework abstracts these differences where possible, but you may need platform-specific configuration for advanced use cases.

​
Next steps

Home Manager modules

Per-user configuration that works on both NixOS and Darwin

Base modules

Shared configuration between platforms

Build docs developers (and LLMs) love

Get started for freeTalk to us