nix

Files (1)

• SKILL.md

SKILL.md (first lines)

# nix

Manage packages and environments using the `nix` CLI.

## Orientation

You must run the following commands before proceeding:

```bash
which -a nix
which nix
nix --version
nix --help
```

## Workflow

1. Confirm the tool is present: `nix --version`
2. Review subcommands: `nix --help`
3. Run a package without installing: `nix run nixpkgs#<package>`
4. Open a shell with packages: `nix shell nixpkgs#<package>`
5. Install to profile: `nix profile install nixpkgs#<package>`
6. Build a derivation: `nix build`
7. Update flake inputs: `nix flake update`

## Installing Unfree Packages

Some packages (e.g. `1password-cli`, `vscode`, `slack`) have unfree licenses and are blocked by default.

### The problem

The modern `nix` CLI (flake-based) runs in **pure evaluation mode** by default, which means:
- `~/.config/nixpkgs/config.nix` with `{ allowUnfree = true; }` is **ignored**
- `--option nixpkgs-config ...` is **not a recognized setting**
- The `NIXPKGS_ALLOW_UNFREE` env var is only read in `--impure` mode

### The solution

Always pass `--impure` when installing unfree packages:

```bash
NIXPKGS_ALLOW_UNFREE=1 nix profile add --impure nixpkgs#<package>
```

Or, if `NIXPKGS_ALLOW_UNFREE=1` is already set in your shell environment (e.g. `.bashrc`):

```bash
nix profile add --impure nixpkgs#<package>
```

> **Note:** `--impure` is the critical flag — without it, nix ignores environment variables entirely.

### What doesn't work

| Method | Works? |
|---|---|
| `~/.config/nixpkgs/config.nix` `{ allowUnfree = true; }` | No — ignored by flake CLI |
| `--option nixpkgs-config '{ allowUnfree = true; }'` | No — unknown setting |
| `NIXPKGS_ALLOW_UNFREE=1` without `--impure` | No — env vars ignored in pure mode |
| `NIXPKGS_ALLOW_UNFREE=1` **with** `--impure` | **Yes** |

## Gotchas

- `nix --version` shows both Nix and (if Determinate Nix) the distribution version.
- Each subcommand has its own help: `nix run --help`, `nix shell --help`, etc.
- Experimental features (`nix flake`, `nix profile`) may require `--extra-experimental-features` on older installs.
- **`nix profile upgrade '<name>'` uses the package's display name, not the flake attribute.** The profile list shows `Name:` (e.g. `devenv`) and `Flake attribute:` (e.g. `legacyPackages.x86_64-linux.devenv`). Use the simple `Name` value: `nix profile upgrade devenv`. Passing `packages.x86_64-linux.devenv` or `legacyPackages.x86_64-linux.devenv` fails with `Package name '...' does not match any packages in the profile`.
- **`nix profile list` shows `Name` and `Flake attribute` separately.** To find a package's install name for `nix profile remove` / `nix profile upgrade`, grep the `Name:` field, not the `Flake attribute:` field.

## Troubleshooting

### "the user 'nixbld1' in the group 'nixbld' does not exist"

Fatal build error on multi-user Nix installs (Determinate Nix or standard
multi-user). The `nixbld` group exists but its member user accounts are
missing from `/etc/passwd`. The daemon enumerates group members at build
time and fails on the first missing user.

**Diagnose:**

```bash
# Confirm the group exists but its members don't
getent group nixbld
# nixbld:x:30000:nixbld1,nixbld2,...,nixbld32

getent passwd nixbld1
# (empty output = user is MISSING)

# Check the installer receipt for the exact UID range
cat /nix/receipt.json | python3 -c "
import json, sys
r = json.load(sys.stdin)
for a in r.get('actions', []):
    act = a.get('action', {})
    if act.get('action_name') == 'create_users_and_group':
        print(f\"group: {act['nix_build_group_name']} gid={act['nix_build_group_id']}\")
        print(f\"users: {act['nix_build_user_count']} prefix={act['nix_build_user_prefix']}\")
        print(f\"uid range: {act['nix_build_user_id_base']+1}..{act['nix_build_user_id_base']+act['nix_build_user_count']}\")
"
```

**Fix — recreate the build users matching the receipt (requires root):**

```bash
sudo bash -c '
set -euo pipefail
for i in $(seq 1 32); do
  uid=$((30000 + i))   # adjust base/count from receipt
  username="nixbld$i"
  getent passwd "$username" >/dev/null 2>&1 || \
    useradd -c "Nix build user $i" -d /var/empty -s /sbin/nologin \
            -g nixbld -u "$uid" -r -M "$username"
done
'
sudo systemctl restart nix-daemon
```

The `useradd` warning `uid 30001 is greater than SYS_UID_MAX 999` is expected
and harmless — Determinate Nix deliberately uses UIDs in the 30000 range to

From jason-riddle/agent-skills, MIT.

More from jason-riddle/agent-skills