nix-darwin: Declarative macOS System Configuration Using Nix Modules

What nix-darwin Manages and Who It Is For

nix-darwin targets macOS users who already know Nix and want to apply the same declarative configuration approach they use on NixOS to their Mac. Instead of running ad hoc commands to install packages, configure system settings, or set up launch agents, you describe the desired state in a Nix module file and apply it with a single command.

The system manages package installation through Nixpkgs, environment configuration, system-level launchd services, shell configuration, and macOS system preferences. The primary audience is developers and power users who manage their workstations as code, version-control their configuration, and want reproducible environments across multiple machines.

How nix-darwin Works: The Module System

nix-darwin is built around the same Nix module system as NixOS. A module is a Nix expression that declares options and their implementations. System configuration is composed by including modules from Nixpkgs, from nix-darwin itself, and from your own configuration files.

When you run `darwin-rebuild switch`, nix-darwin evaluates your configuration, computes the changes needed, and applies them atomically. Packages are installed or removed from the Nix store, symlinks in `/run/current-system` are updated, and launchd agents are registered or deregistered. If the build fails, the running system is unaffected.

The reference documentation is available online at https://nix-darwin.github.io/nix-darwin/manual/index.html, locally in a browser with the `darwin-help` command, and as a man page via `man 5 configuration.nix`.

Both Nix and Lix are supported as the underlying Nix implementation. The README recommends the Lix installer for new setups because the official Nix installer does not include an automated uninstaller on macOS, which makes manual removal complex. After installation, you can set `nix.package = pkgs.lix` to use Lix as the interpreter.

Installing nix-darwin with Flakes

The README recommends the flakes method for beginners. First, create the configuration directory and initialize a flake:

sudo mkdir -p /etc/nix-darwin
sudo chown $(id -nu):$(id -ng) /etc/nix-darwin
cd /etc/nix-darwin
nix flake init -t nix-darwin/master
sed -i '' "s/simple/$(scutil --get LocalHostName)/" flake.nix

Set `nixpkgs.hostPlatform` to `x86_64-darwin` for Intel or `aarch64-darwin` for Apple Silicon in your flake. Then run the initial build:

sudo nix run nix-darwin/master#darwin-rebuild -- switch

After the first build, `darwin-rebuild` is installed in your PATH. Apply subsequent changes with:

sudo darwin-rebuild switch

For the channels-based setup (an alternative to flakes), the install process is slightly different: add the nix-darwin channel, update, then run `nix-build '<darwin>' -A darwin-rebuild` to get the bootstrap binary before running `darwin-rebuild switch` with the `-I darwin-config=` flag pointing to your configuration file.

Uninstalling nix-darwin

nix-darwin ships a dedicated uninstaller. To run the latest version:

sudo nix --extra-experimental-features "nix-command flakes" run nix-darwin#darwin-uninstaller

If that command fails, the locally installed uninstaller is also available:

sudo darwin-uninstaller

The README also documents how to update Nixpkgs and nix-darwin using channels:

sudo nix-channel --update

This is one area where nix-darwin is more ergonomic than the underlying Nix installation: the darwin-uninstaller handles the macOS-specific cleanup steps that the official Nix installer's lack of an uninstaller makes difficult to do manually.

nix-darwin vs Homebrew and Home Manager

Homebrew is the dominant package manager for macOS. It installs packages as binaries or from source into `/opt/homebrew`, is familiar to most Mac developers, and has a vast formula library. The key difference from nix-darwin is that Homebrew is imperative: you run commands to install and remove packages, and the system state is whatever commands you last ran. nix-darwin is declarative: the system state is defined in a file and enforced on every `darwin-rebuild switch`.

Home Manager is a Nix-based tool for managing per-user dotfiles, shell configuration, and user-installed packages. It works on both macOS and Linux and does not require system-level privileges. nix-darwin manages system-level settings such as launchd services, system fonts, and `/etc` files, which Home Manager does not. The two are commonly used together: nix-darwin for system-level configuration and Home Manager for user-level dotfiles. The README supports this by referencing the home-manager channel and flake setups in the related searches context.

Limitations and Failure Modes

The most significant practical limitation is that nix-darwin can only manage what has been implemented as a Nix module option. macOS system preferences, application settings, and third-party services that have no corresponding nix-darwin module option must still be configured manually. The module library grows over time, but there are always macOS capabilities that lag.

Building a broken configuration does not break the running system, which is good, but debugging the error requires reading Nix evaluation output. New users who are not comfortable with Nix's error messages will find this steep.

The README also notes that the official Nix installer does not include an automated uninstaller, making removal complex for users who abandon nix-darwin. This is a one-time cost if you decide nix-darwin is not for you, but it is a real friction point.

Finally, macOS system updates from Apple can break nix-darwin configurations, particularly around `/etc` files that Apple regenerates. The nix-darwin project tracks these changes, but updates require waiting for a compatible nix-darwin release or applying manual workarounds.

Repository Layout and Maintenance

The repository is MIT licensed and not archived. The last push was on 2026-08-16. There are no GitHub releases; versioning follows Nixpkgs channel names and flake references (`nix-darwin/master` for unstable, `nix-darwin/nix-darwin-26.05` for the stable release branch tracking Nixpkgs 26.05).

The directory structure follows Nix conventions: `modules/` contains the declarative option definitions, `pkgs/` contains nix-darwin-specific package derivations, `tests/` contains sanity-check builds, and `doc/` holds the module documentation source. Tests can be run with:

nix-build release.nix -A tests

Contributors adding new modules should add themselves to `meta.maintainers` within the module, using the `lib.maintainers.alice or "alice"` pattern to handle graceful degradation when the Nixpkgs `lib` version goes out of sync.

Editorial conclusion

nix-darwin is a strong choice for macOS developers who already use Nix and want to bring their machine's system configuration under declarative version control, including launchd services, environment variables, and installed packages from Nixpkgs. It is the wrong tool for users who are new to Nix: the learning curve is steep, the official Nix installer does not include an automated uninstaller on macOS, and debugging broken configurations requires Nix-specific knowledge. Teams already using Homebrew and satisfied with it have no pressing reason to switch. Start by evaluating whether you need system-level services and package management, or only per-user dotfiles; if the latter, Home Manager alone is sufficient and simpler.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. nix-darwin/nix-darwin on GitHub
4. Project website
5. README