nix-darwin

Nix modules for darwin,/etc/nixos/configuration.nixfor macOS.

This project aims to bring the convenience of a declarative system approach to macOS. nix-darwin is built up aroundNixpkgs,quite similar toNixOS.

Installing

To install nix-darwin, a working installation ofNixis required.

If you wish to use nix-darwin with flakes, please refer to theflakessection.

nix-build https://github /LnL7/nix-darwin/archive/master.tar.gz -A installer
./result/bin/darwin-installer

NOTE: the system activation scripts don't overwrite existing etc files, so files like/etc/bashrcand/etc/zshrcwon't be updated by default. If you didn't use the installer or skipped some of the options you'll have to take care of this yourself. Either modify the existing file to source/import the one from/etc/staticor remove it. Some examples:

• mv /etc/bashrc /etc/bashrc.before-nix-darwin
• echo 'if test -e /etc/static/bashrc; then. /etc/static/bashrc; fi' | sudo tee -a /etc/bashrc

Updating

The installer will configure a channel for this repository.

nix-channel --update darwin
darwin-rebuild changelog

NOTE: If you are using Nix as a daemon service the channel for that will be owned by root. Usesudo -i nix-channel --update darwininstead.

Uninstalling

To run the latest version of the uninstaller, you can run the following command:

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

If that command doesn't work for you, you can try the locally installed uninstaller:

darwin-uninstaller

Example configuration

Configuration lives in~/.nixpkgs/darwin-configuration.nix.Check out modules/examplesfor some example configurations.

{pkgs,...}:
{
# List packages installed in system profile. To search by name, run:
# $ nix-env -qaP | grep wget
environment.systemPackages=
[pkgs.vim
];

# Auto upgrade nix package and the daemon service.
services.nix-daemon.enable=true;
nix.package=pkgs.nix;
}

Flakes

nix-darwin aims for both non-flake and flake configurations to be well supported despite flakes being an experimental feature in Nix.

Step 1. Creatingflake.nix

Getting started from scratch

If you don't have an existingconfiguration.nix,you can run the following commands to generate a basicflake.nixinside~/.config/nix-darwin:

mkdir -p~/.config/nix-darwin
cd~/.config/nix-darwin
nix flake init -t nix-darwin
sed -i''"s/simple/$(scutil --get LocalHostName)/"flake.nix

Make sure to changenixpkgs.hostPlatformtoaarch64-darwinif you are using Apple Silicon.

Migrating from an existing configuration.nix

Add the following toflake.nixin the same folder asconfiguration.nix:

{
description="John's darwin system";

inputs={
nixpkgs.url="github:NixOS/nixpkgs/nixpkgs-24.05-darwin";
nix-darwin.url="github:LnL7/nix-darwin";
nix-darwin.inputs.nixpkgs.follows="nixpkgs";
};

outputs=inputs@{self,nix-darwin,nixpkgs}:{
darwinConfigurations."Johns-MacBook"=nix-darwin.lib.darwinSystem{
modules=[./configuration.nix];
};
};
}

Make sure to replaceJohns-MacBookwith your hostname which you can find by runningscutil --get LocalHostName.

Make sure to setnixpkgs.hostPlatformin yourconfiguration.nixto eitherx86_64-darwin(Intel) oraarch64-darwin(Apple Silicon).

Step 2. Installingnix-darwin

Instead of usingdarwin-installer,you can just rundarwin-rebuild switchto install nix-darwin. Asdarwin-rebuildwon't be installed in yourPATHyet, you can use the following command:

nix run nix-darwin -- switch --flake~/.config/nix-darwin

Step 3. Usingnix-darwin

After installing, you can rundarwin-rebuildto apply changes to your system:

darwin-rebuild switch --flake~/.config/nix-darwin

Using flake inputs

Inputs from the flake can also be passed intodarwinSystem.These inputs are then accessible as an argumentinputs,similar topkgsandlib,inside the configuration.

# in flake.nix
nix-darwin.lib.darwinSystem{
modules=[./configuration.nix];
specialArgs={inheritinputs;};
}

# in configuration.nix
{pkgs,lib,inputs}:
# inputs.self, inputs.nix-darwin, and inputs.nixpkgs can be accessed here

Documentation

Reference documentation of all the options is availablehere. This can also be accessed locally usingman 5 configuration.nix.

darwin-helpwill open a HTML version of the manpage in the default browser.

Furthermore there'sdarwin-optionto introspect the settings of a system and its available options.

NOTE:darwin-optionis only available to non-flake installations.

$ darwin-option services.activate-system.enable
Value:
true

Default:
false

Example:
no example

Description:
Whether to activate system at boot time.

There's also a small wikihttps://github /LnL7/nix-darwin/wikiabout specific topics, like macOS upgrades.

Tests

There are basic tests that run sanity checks for some of the modules, you can run them like this:

#run all tests
nix-build release.nix -A tests
#or just a subset
nix-build release.nix -A tests.environment-path

Contributing

Let's make Nix on macOS awesome!

Don't hesitate to contribute modules or open an issue.

To build your configuration with local changes you can run this. This flag can also be used to override darwin-config or nixpkgs, for more information on the-Iflag look at the nix-buildmanpage.

darwin-rebuild switch -I darwin=.

If you're adding a module, please add yourself tometa.maintainers,for example

meta.maintainers=[
lib.maintainers.aliceor"alice"
];

options.services.alicebot=#...

Theoroperator takes care of graceful degradation whenlibfrom Nixpkgs goes out of sync.

Also feel free to contact me if you have questions,

• Matrix - @daiderd:matrix.org, you can find me in#macos:nixos.org
• @LnL7 on twitter