Repository files navigation

Hey, you made it! Welcome. 🤓

Nix is a powerful package manager for Linux and Unix systems that ensures reproducible, declarative, and reliable software management.

This repository contains configuration for a general-purpose development environment that runs Nix on macOS, NixOS, or both simultaneously.

I use it daily on my 🧑🏻‍💻 Macbook Pro and an x86 PC in my home office. It also runs as a VM on your Mac. Many others have reported that it's working for them too.

Check out the step-by-step commands below to get started!

• Nix Config for macOS + NixOS
  • Overview
  • Table of Contents
  • Features
  • Testimonials
  • Videos
    • macOS
      • Updating dependencies with one command
      • Instant Emacs 30 thanks to daemon mode
    • NixOS
  • Disclaimer
  • Layout
  • Installing
    • For macOS (October 2025)
      • 1. Install dependencies
      • 2. Install Nix
      • 3. Initialize a starter template
      • 4. Make apps executable
      • 5. Apply your current user info
      • 6. Decide what packages to install
      • 7. Review your shell configuration
      • 8. Optional: Setup secrets
      • 9. Install configuration
      • 10. Make changes
    • For NixOS
      • 1. Burn and use the latest ISO
      • 2. Optional: Setup secrets
      • 3. Install configuration
      • 4. Set user password
  • How to Create Secrets
  • Making Changes
    • Development workflow
    • Trying packages
  • Compatibility and Feedback
    • Platforms
    • Contributing
    • Feedback and Questions
    • License
  • Appendix
    • Why Nix Flakes
    • NixOS Components
    • Support
    • Stars

• Nix Flakes: No confusingconfiguration.nix entry point,no Nix channels─ justflake.nix
• Same Environment Everywhere: Easily share config across Linux and macOS (both Nix and Home Manager)
• macOS Dream Setup: Fully declarative macOS (Apple / Intel) w/ UI, dock and macOS App Store apps
• Simple Bootstrap: Simple Nix commands to start from zero, both x86 and macOS platforms
• Managed Homebrew: Zero maintenance homebrew environment withnix-darwin andnix-homebrew
• Disk Management: Declarative disk management withdisko, say goodbye to disk utils
• Secrets Management: Declarative secrets withagenix for SSH, PGP, syncthing, and other tools
• Super Fast Emacs: Bleeding edge Emacs that fixes itself, thanks to acommunity overlay
• Built In Home Manager:home-manager module for seamless configuration (no extra clunky CLI steps)
• NixOS Environment: Extensively configured NixOS including clean aesthetic + window animations
• Nix Overlays:Auto-loading of Nix overlays: drop a file in a dir and it runs(great for patches!)
• Declarative Sync: No-fuss Syncthing: managed keys, certs, and configuration across all platforms
• Emacs Literate Configuration:Large Emacs literate configuration to explore (if that's your thing)
• Simplicity and Readability: Optimized for simplicity and readability in all cases, not small files everywhere
• Backed by Continuous Integration: Flake auto updates weekly if changes don't break starter build

• GUI

• Terminal

Installing Nix on macOS will create an entirely separate volume. It may exceed many gigabytes in size.

Some folks don't like this. If this is you, turn back now!

.├── apps         # Nix commands used to bootstrap and build configuration├── hosts        # Host-specific configuration├── modules      # macOS and nix-darwin, NixOS, and shared configuration├── overlays     # Drop an overlay file in this dir, and it runs. So far, mainly patches.├── templates    # Starter versions of this configuration

This configuration supports both Intel and Apple Silicon Macs.

xcode-select --install

Thank you for theinstaller,Determinate Systems!

curl --proto'=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix| sh -s -- install

After installation, open a new terminal session to make thenix executable available in your$PATH. You'll need this in the steps ahead.

experimental-features = nix-command flakes

nix --extra-experimental-features 'nix-command flakes' run .#<command>

Choose one of two options

Simplified version without secrets management

• Great for beginners, enables you to get started quickly and test out Nix.
• Forgoing secrets just means you must configure apps that depend on keys, passwords, etc., yourself.
• You can always add secrets later.

mkdir -p nixos-config&&cd nixos-config&& nix flake --extra-experimental-features'nix-command flakes' init -t github:dustinlyons/nixos-config#starter

Full version with secrets management

• Choose this to add more moving parts for a 100% declarative configuration.
• This template offers you a place to keep passwords, private keys, etc.as part of your configuration.

mkdir -p nixos-config&&cd nixos-config&& nix flake --extra-experimental-features'nix-command flakes' init -t github:dustinlyons/nixos-config#starter-with-secrets

find apps/$(uname -m| sed's/arm64/aarch64/')-darwin -type f\( -name apply -o -name build -o -name build-switch -o -name create-keys -o -name copy-keys -o -name check-keys -o -name rollback\) -exec chmod +x {}\;

Run this Nix command to replace stub values with your system properties, username, full name, and email.

Your email is only used in thegit configuration.

nix run .#apply

You can search for packages on theofficial NixOS website.

Review these files

• modules/darwin/casks.nix
• modules/darwin/packages.nix
• modules/shared/packages.nix

Add anything from your existing~/.zshrc, or just review the new configuration.

Review these files

• modules/darwin/home-manager
• modules/shared/home-manager

If you are using the starter with secrets, there are a few additional steps.

In Github, create a privatenix-secrets repository with at least one file (like aREADME). You'll enter this name during installation.

Before generating your first build, these keys must exist in your~/.ssh directory. Don't worry, I provide a few commands to help you.

Run one of these commands:

This command auto-detects a USB drive connected to the current system.

Keys must be namedid_ed25519 andid_ed25519_agenix.

nix run .#copy-keys

nix run .#create-keys

cat /Users/$USER/.ssh/id_ed25519.pub| pbcopy# Copy key to clipboard

If you're rolling your own, just check they are installed correctly.

nix run .#check-keys

Ensure the build works before deploying the configuration, run:

nix run .#build

The following files have unrecognized content and would be overwritten:  /etc/nix/nix.conf  /etc/bashrcPlease check there is nothing critical in these files, rename them by adding .before-nix-darwin to the end, and then try again.

error: Build user group has mismatching GID, aborting activationThe default Nix build user group ID was changed from 30000 to 350.You are currently managing Nix build users with nix-darwin, but yournixbld group has GID 350, whereas we expected 30000.

Finally, alter your system with this command:

nix run .#build-switch

This configuration supports bothx86_64 andaarch64 platforms.

Download and burnthe minimal ISO image to a USB, or create a new VM with the ISO as base. Boot the installer.

If you're building a VM on an Apple Silicon Mac, choose64-bit ARM.

Quick Links

• 64-bit Intel/AMD
• 64-bit ARM

If you are using the starter with secrets, there are a few additional steps.

In Github, create a privatenix-secrets repository with at least one file (like aREADME). You'll enter this name during installation.

Before generating your first build, these keys must exist in your~/.ssh directory. Don't worry, I provide a few commands to help you.

Run one of these commands:

This command auto-detects a USB drive connected to the current system.

Keys must be namedid_ed25519 andid_ed25519_agenix.

sudo nix run --extra-experimental-features'nix-command flakes' github:dustinlyons/nixos-config#copy-keys

sudo nix run --extra-experimental-features'nix-command flakes' github:dustinlyons/nixos-config#create-keys

If you're rolling your own, just check they are installed correctly.

sudo nix run --extra-experimental-features'nix-command flakes' github:dustinlyons/nixos-config#check-keys

Simple

• Great for beginners, enables you to get started quickly and test out Nix.
• Forgoing secrets means you must configure apps that depend on keys or passwords yourself.
• You can always add secrets later.

sudo nix run --extra-experimental-features'nix-command flakes' github:dustinlyons/nixos-config#install

With secrets

• Choose this to add more moving parts for a 100% declarative configuration.
• This template offers you a place to keep passwords, private keys, etc.as part of your configuration.

sudo nix run --extra-experimental-features'nix-command flakes' github:dustinlyons/nixos-config#install-with-secrets

On first boot at the login screen:

• Use shortcutCtrl-Alt-F2 (orFn-Ctrl-Option-F2 if on a Mac) to move to a terminal session
• Login asroot using the password created during installation
• Set the user password withpasswd <user>
• Go back to the login screen:Ctrl-Alt-F7
• Review the essential hotkeys inNixOS README to get started with the bspwm window manager

To create a new secretsecret.age, firstcreate asecrets.nix file at the root of yournix-secrets repository. Use this code:

secrets.nix

letuser1="ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIL0idNvgGiucWgup/mP78zyC23uFjYq0evcWdjGQUaBH";users=[user1];system1="ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIPJDyIr/FSz1cJdcoW69R+NrWzwGK/+3gJpqD1t8L2zE";systems=[system1];in{"secret.age".publicKeys=[user1system1];}

Values foruser1 should be your public key, or if you prefer to have keys attached to hosts, use thesystem1 declaration.

Now that we've configuredagenix with oursecrets.nix, it's time to create our first secret.

Run the command below.

EDITOR=vim nix run github:ryantm/agenix -- -e secret.age

This opens an editor to accept, encrypt, and write your secret to disk.

The command will look up the public key forsecret.age, defined in yoursecrets.nix, and check for its private key in~/.ssh/.

To override the SSH path, provide the-i flag with a path to yourid_ed25519 key.

Write your secret in the editor, save, and commit the file to yournix-secrets repo.

Now we have two files:secrets.nix and oursecret.age.

Here's a more step-by-step example:

Let's say I wanted to create a new secret to hold my Github SSH key.

I wouldcd into mynix-secrets repo directory, verify theagenix configuration (namedsecrets.nix) exists, then run

EDITOR=vim nix run github:ryantm/agenix -- -e github-ssh-key.age

This would start avim session.

I would enter insert mode:i, copy+paste the key, hit Esc and then type:w to save it, resulting in the creation of a new file,github-ssh-key.age.

Then, I would editsecrets.nix to include a line specifying the public key to use for my new secret. I specify a user key, but I could just as easily specify a host key.

secrets.nix

letdustin="ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIL0idNvgGiucWgup/mP78zyC23uFjYq0evcWdjGQUaBH";users=[dustin];systems=[];in{"github-ssh-key.age".publicKeys=[dustin];}

Finally, I'd commit all changes to thenix-secrets repository, go back to mynixos-config and runnix flake update to update the lock file.

The secret is now ready to use. Here's anexample from my configuration. In the end, this creates a symlink to a decrypted file in the Nix Store that reflects my original file.

With Nix, changes to your system are made by

• editing your system configuration
• building thesystem closure
• creatinga new generation based on this closure and switching to it

This is all wrapped up in thebuild-switch run command.

So, in general, the workflow for managing your environment will look like

• make changes to the configuration
• runnix run .#build-switch
• watch Nix,nix-darwin,home-manager, etc do their thing
• go about your way and benefit from a declarative environment

For quickly trying a package without installing it, I usually run

nix shell nixpkgs#hello

wherehello is the package name fromnixpkgs.

This configuration has been tested and confirmed to work on the following platforms:

• Newer M1/M2/M3 Apple Silicon Macs
• Older x86_64 (Intel) Macs
• Bare metal x86_64 PCs
• NixOS VMs inside VMWare on macOS
• macOS Sonoma VMs inside Parallels on macOS

Have feedback or questions? Feel free to use thediscussion forum.

Interested in contributing to this project? Here's how you can help:

• Code Contributions: If you're interested in contributing code, please start by looking at open issues or feature requests. Fork the repository, make your changes, and submit a pull request. Make sure your code adheres to the existing style. For significant changes, consider opening an issue for discussion before starting work.

• Reporting Bugs: If you encounter bugs or issues, please help by reporting them. Open a GitHub Issue and include as much detail as possible: what you were doing when the bug occurred, steps to reproduce the issue, and any relevant logs or error messages.

Reasons to jump into flakes and skipnix-env, Nix channels, etc

• Flakes work just like other package managers you already know:npm,cargo,poetry,composer, etc. Channels work more like traditional Linux distributions (like Ubuntu), which most devs don't know.
• Flakes encapsulate not just project dependencies, but Nix expressions, Nix apps, and other configurations in a single file. It's all there in a single file. This is nice.
• Channels lock all packages to one big globalnixpkgs version. Flakes lock each individual package to a version, which is more precise and makes it much easier to manage overall.
• Flakes have a growing ecosystem (seeFlake Hub orDev Env), so you're future-proofing yourself.

This project is released under theBSD-3-Clause license.

Did you find my project useful? Your support is appreciated.

"All we have to decide is what to do with the time that is given us." - J.R.R. Tolkien