Manage macOS systems using Nix flakes, nix-darwin, and home-manager with a modular configuration structure
Expert guidance for working with Nix flake-based macOS system configurations using nix-darwin and home-manager.
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.
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)
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
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
```
```nix
environment.systemPackages = with pkgs; [
# Existing packages...
new-package-name
];
```
```nix
home.packages = with pkgs; [
# Existing packages...
new-cli-tool
];
```
```nix
programs.git = {
enable = true;
userName = "Your Name";
userEmail = "[email protected]";
extraConfig = {
init.defaultBranch = "main";
};
};
```
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`
**Nix Configuration:**
**macOS Customization:**
**Terminal Environment:**
**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
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
When working with this configuration, you may need to:
Leave a review
No reviews yet. Be the first to review this skill!
# Download SKILL.md from killerskills.ai/api/skills/nix-darwin-system-management/raw