// Use this when diagnosing or fixing a user's Nix installation — checks flakes, version, caches, max-jobs, direnv, rosetta, trusted-users, and shell config
| name | nix-health |
| description | Use this when diagnosing or fixing a user's Nix installation — checks flakes, version, caches, max-jobs, direnv, rosetta, trusted-users, and shell config |
Run these checks to diagnose problems with a Nix installation. For each failing check, report the issue and suggestion to the user.
Identify which installer was used:
# NixOS/nix-installer and Determinate Nix both leave a receipt:
cat /nix/receipt.json 2>/dev/null | python3 -c "import sys,json; print(json.load(sys.stdin).get('version','unknown'))" 2>/dev/null
# On macOS, check launchd service names:
ls /Library/LaunchDaemons/*nix* /Library/LaunchDaemons/*determinate* 2>/dev/null
# On Linux, check systemd:
systemctl list-units '*nix*' '*determinate*' --no-pager 2>/dev/null
# Check for determinate-nixd (Determinate Nix specific):
which determinate-nixd 2>/dev/null
determinate-nixd exists or systems.determinate.* services are present → ⚠️ Determinate Nix detected (proprietary fork). Suggestion: Switch to the official installer or NixOS/nix-installer for a fully open-source Nix. See https://nixos.org/download//nix/receipt.json exists but no determinate-nixd → ℹ️ NixOS/nix-installer (community, formerly DeterminateSystems/nix-installer)org.nixos.nix-daemon (macOS) or nix-daemon.service (Linux) → ℹ️ Official installernix config show 2>/dev/null | grep '^experimental-features'
Value must contain both flakes and nix-command. If missing:
nix --version
Version must be ≥ 2.16.0. If older:
nix config show 2>/dev/null | grep '^max-jobs'
Value must be > 1 (ideally auto). If set to 1:
max-jobs = auto in /etc/nix/nix.conf (Linux) or ~/.config/nix/nix.conf (macOS without nix-darwin). On NixOS use nix.settings.max-jobs = "auto". On nix-darwin use the same option.nix config show 2>/dev/null | grep '^substituters'
Must include https://cache.nixos.org. Also check for project-specific caches defined in:
nixConfig.extra-substituters in the project's flake.nixcache.url in the project's vira.hs (Vira CI config)If any required caches are missing from the user's substituters:
substituters. For Cachix caches run nix run nixpkgs#cachix use <name>.nix config show 2>/dev/null | grep '^trusted-users'
whoami
The current user (or a group they belong to, or *) should appear in trusted-users. If missing:
nix.settings.trusted-users = [ "root" "<user>" ];trusted-users = root <user> to /etc/nix/nix.conf and restart the daemon (sudo pkill nix-daemon)which direnv 2>/dev/null && readlink -f "$(which direnv)"
Direnv should be installed and its resolved path should be inside /nix/store/. If not installed or installed outside Nix:
Only check on Apple Silicon Macs:
sysctl -n sysctl.proc_translated 2>/dev/null
If the value is 1, Nix is running under Rosetta emulation which slows builds:
aarch64-darwin. See https://nixos.asia/en/installwhich brew 2>/dev/null
If Homebrew is installed, flag as ⚠️ — it can interfere with Nix environments (e.g. conflicting library paths, shadowed binaries).
brew list, install equivalents via Nix, then consider removing Homebrew.Check if shell config files are managed by Nix (symlinked into /nix/store):
# For zsh:
ls -la ~/.zshrc ~/.zshenv ~/.zprofile ~/.zlogin ~/.zlogout 2>/dev/null
# For bash:
ls -la ~/.bashrc ~/.bash_profile ~/.profile 2>/dev/null
Any dotfile whose resolved path is not under /nix/store/ is unmanaged — flag it as ⚠️.
Present results as a table with columns: Check, Status (✅/❌/⚠️), Details, and Suggestion (if failing). Mark checks that don't apply to the current OS as skipped.
Use this when setting up Nix for a development project (devShell + package build) and you care about `nix develop` being fast. Covers the zero-inputs flake.nix + npins + default.nix/shell.nix layout, sub-flakes for non-user-facing Nix, and language-specific recommendations.
Use this when a flake's `nix develop` / `direnv allow` / `nix flake archive` is slow on a fresh checkout (the "first time takes 10 minutes" complaint). Diagnoses where the time actually lives and how to shrink the flake.lock input graph without changing build outputs.
Use this when adding Nix-based local runs for an existing Playwright e2e suite. Provides a self-contained `tests/shell.nix` that uses `nixpkgs-latest` for `playwright-driver.browsers`, plus a justfile entry — works on NixOS where `npx playwright install --with-deps` cannot.
Write a programming essay or blog post in the voice of the canon — Spolsky, Yegge, Graham, Mickens, Dijkstra, Brooks, Nystrom, Kleppmann, patio11. Invoke when the user wants to argue an idea about software, architecture, languages, or the craft — not a debugging war story (use debugging-story for that), not a tutorial, not a release note. The audience is working developers worldwide with taste and strong opinions of their own.
Use this when setting up CI for a GitHub repository — offers GitHub Actions or Vira depending on the project
Use this when working on a Haskell project with Nix. Covers haskell-flake setup, adding/overriding dependencies, package settings, and devShell configuration.