Nix Darwin System Management

Expert guidance for working with Nix flake-based macOS system configurations using nix-darwin and home-manager.

What This Skill Does

This skill helps you work with declarative macOS system configurations managed through Nix flakes. It covers system-level settings via nix-darwin, user-level package management via home-manager, and provides guidance on the modular structure used to organize terminal environments, development tools, and system preferences.

Repository Architecture

The configuration follows a modular structure:

**Core Configuration:**

**System Modules (`modules/`):**

**Home Configuration (`home/`):**

- `shell/` - Shell configurations (zsh with Oh My Zsh, fish, starship prompt)

- `emulators/` - Terminal emulators (wezterm, ghostty)

- `programs/` - CLI tools organized by category (development, utilities, editors)

Common System Operations

Building and Switching Configurations

1. **Apply system configuration:**

```bash

just darwin

```

This builds the flake configuration and switches the system to it (equivalent to `darwin-rebuild switch --flake .#<hostname>`)

2. **Debug build issues:**

```bash

just darwin-debug

```

Builds with verbose output to troubleshoot configuration problems

3. **Update flake inputs:**

```bash

just update

```

Updates nixpkgs and other flake inputs to their latest versions

4. **Format nix files:**

```bash

just fmt

```

Runs `nix fmt` to format all nix files using alejandra formatter

5. **Clean build artifacts:**

```bash

just clean

```

Removes build artifacts and result symlinks

6. **Garbage collection:**

```bash

just gc

```

Removes old system generations (older than 7 days) and runs nix garbage collection

Manual Nix Commands

Making Configuration Changes

Step-by-Step Workflow

1. **Identify the correct module:**

- System-level changes → `modules/` directory

- User packages and dotfiles → `home/` directory

- Terminal tools → `home/terminal/programs/`

- Shell configuration → `home/terminal/shell/`

2. **Edit the appropriate nix file:**

- Use declarative nix syntax

- Add packages to `environment.systemPackages` (system) or `home.packages` (user)

- Configure programs using their home-manager options

3. **Format the changes:**

```bash

just fmt

```

4. **Build and switch:**

```bash

just darwin

```

5. **If issues occur:**

```bash

just darwin-debug

```

Example: Adding a System Package

```nix

In modules/apps.nix

environment.systemPackages = with pkgs; [

# Existing packages...

new-package-name

];

```

Example: Adding a Home Package

```nix

In home/terminal/programs/some-category.nix

home.packages = with pkgs; [

# Existing packages...

new-cli-tool

];

```

Example: Configuring a Program

```nix

In home/terminal/programs/git.nix

programs.git = {

enable = true;

userName = "Your Name";

userEmail = "[email protected]";

extraConfig = {

init.defaultBranch = "main";

};

};

```

Host-Specific Configuration

When deploying to a new machine, update these values:

1. **In `flake.nix`** (around line 29-31):

```nix

user = "your-username";

hostname = "your-hostname";

```

2. **In `Justfile`** (line 4):

```makefile

hostname := "your-hostname"

```

3. **System architecture:**

- Default: `aarch64-darwin` (Apple Silicon)

- Intel Macs: Change to `x86_64-darwin`

Key Features and Settings

**Nix Configuration:**

**macOS Customization:**

**Terminal Environment:**

Troubleshooting

**Build failures:**

1. Check syntax: `nix flake check`

2. Run with debug output: `just darwin-debug`

3. Verify all referenced packages exist in nixpkgs

**Changes not taking effect:**

1. Ensure you ran `just darwin` (not just `just fmt`)

2. Check that the module is imported in the appropriate `default.nix`

3. Some system settings require logout or reboot

**Flake input issues:**

1. Update inputs: `just update`

2. Check flake.lock for version pinning

3. Clear nix evaluation cache if needed

Important Constraints

Best Practices

1. **Always format before committing:** `just fmt`

2. **Test changes locally:** Build before pushing to remote

3. **Keep modules focused:** One category per file in appropriate directory

4. **Use home-manager for user packages:** Reserve system packages for system-wide needs

5. **Document significant changes:** Add comments for non-obvious configurations

6. **Version control:** Commit flake.lock to ensure reproducible builds

Additional Resources

When working with this configuration, you may need to: