Customization¤
The tool is designed for customization at three levels - from individual developers adding a package to organizations distributing standardized environments - without forking the base repository.
Package layers¤
Packages are assembled from four layers, evaluated bottom-up by the Nix flake. All layers merge into a single buildEnv - one nix profile entry, one nix profile upgrade to apply. No layer can shadow or break another.
| Layer | What | How | Who |
|---|---|---|---|
| Base | Core tools (git, jq, curl, coreutils) | Always included, cannot be disabled | Base repo |
| Repo scopes | Curated groups (shell, python, k8s, terraform) | nix/setup.sh --shell --python |
Base repo |
| Overlay scopes | Custom groups (team CLIs, org utilities) | nx overlay add or nx scope add |
Team / org |
| Extra packages | Individual tools | nx install httpie |
Individual |
Adding packages (layer 4)¤
The simplest way - no scopes, no files to edit:
nx install httpie jq # validates against nixpkgs, installs immediately
nx remove httpie # remove a package
nx list # see everything installed, annotated by layer
Package names are validated against nixpkgs before being added. Typos and non-existent packages are caught immediately. Changes apply without needing nx upgrade.
Use this for one-off tools. If you find yourself adding many related packages, consider creating a scope instead.
Creating custom scopes (layer 3)¤
Scopes group related packages with a meaningful name:
# Create a scope and add packages in one step
nx scope add devtools httpie jq bat
# Add more packages to an existing scope
nx scope add devtools fd
# Open a scope in your editor
nx scope edit devtools
# Apply changes after manual edits
nx upgrade
The scope file is standard Nix:
{ pkgs }: with pkgs; [
bat
fd
httpie
jq
]
Scopes created via nx scope add live in your personal scopes folder (~/.config/nix-env/local/) and are copied into ~/.config/nix-env/scopes/ with a local_ prefix - preventing name collisions with base repo scopes.
Packages that are not in nixpkgs¤
A scope file is an ordinary Nix function: it takes pkgs and returns a list of
derivations. The flat package list is only the shape nx scope add writes - it
is not a restriction. You can build a derivation inline and return that, which
is how an overlay ships a tool nixpkgs does not carry without changing this
repo.
This example installs a prebuilt release binary, so it costs a download instead of a source build:
{ pkgs }:
let
version = "0.28.4";
sofka = pkgs.stdenvNoCC.mkDerivation {
pname = "sofka";
inherit version;
src = pkgs.fetchurl {
url = "https://github.com/nklmilojevic/sofka/releases/download/v${version}"
+ "/sofka-v${version}-x86_64-unknown-linux-musl.tar.gz";
sha256 = "72b5b56afc3cb021d5233a63b6d252a4b8375c420a887da1e58be803cafdae0b";
};
sourceRoot = ".";
installPhase = ''
runHook preInstall
install -Dm755 sofka "$out/bin/sofka"
runHook postInstall
'';
};
in
[ sofka ]
Things worth knowing:
- Prefer a statically linked release asset - a
muslbuild on Linux. A dynamically linked binary also needspkgs.autoPatchelfHookinnativeBuildInputsand its shared libraries inbuildInputs. sourceRoot = "."is for a flat archive that has no top-level directory.- This example pins one platform. To cover several, look the URL and hash up in
an attribute set keyed on
pkgs.stdenv.hostPlatform.system. nx scope addcannot add such a package, because it checks every name against nixpkgs. Create the scope withnx scope add <name>, then write the derivation withnx scope edit <name>.- After a scope file contains hand-written Nix,
nx scope add <name> <pkg>refuses to touch it. That command rebuilds the file from package names alone and would discard everything else. Edit the file directly instead.
Overlays and personal scopes¤
Two places add scopes on top of the standard ones:
| Source | Where it comes from | Owned by |
|---|---|---|
| Overlays | a repository, subscribed by name with nx overlay add |
a team or org, or an image |
| Personal scopes | ~/.config/nix-env/local/, written by nx scope add |
you |
Overlays¤
An overlay is a named set of scopes in a repository. Subscribe to one, and every nx setup and
nx upgrade keeps it current:
nx overlay browse github:<org>/dev-overlays # what the repository offers
nx overlay add github:<org>/dev-overlays k8s # subscribe by name and apply
nx overlay # subscriptions and their scopes
nx overlay remove k8s # unsubscribe
Its scopes are named <overlay>/<scope>. Opt out of one with nx scope remove k8s/sofka; it stays out
across updates until nx scope add k8s/sofka. Run nx setup after an overlay adds a header scope with
install steps, such as the gcloud CLI, which nx upgrade skips. Writing an overlay, addresses, shell config,
hooks and images are covered in Overlays.
Personal scopes¤
nx scope add keeps your own scope files in ~/.config/nix-env/local/scopes/. Every setup run copies each
one in as local_<name>.nix and enables it; nx scope remove deletes it. A file in
~/.config/nix-env/local/shell_cfg/ is sourced at login and wins over an overlay file of the same name.
A scope file can also name the standard scopes it needs, in a # scopes: header:
# scopes: python nodejs gcloud k8s_base
# bins: btop psql
{ pkgs }: with pkgs; [
btop
postgresql
]
Setup enables those scopes as if they were passed as flags, with their dependencies and install steps.
An unknown name prints a warning and is skipped. When a name drops out of the header, setup removes that
scope once, with its remove step, and prints it. On an unattended run that step deletes the scope's
home folder too, for example ~/google-cloud-sdk for gcloud. A user who adds the scope back keeps it.
Hooks¤
Hook scripts (*.sh) run at defined phases during nix/setup.sh.
Per-machine hooks live in ~/.config/nix-env/hooks/. They are sourced into setup, so they can read and
change its variables:
| Phase | Directory | Variables available |
|---|---|---|
| Pre-setup | ~/.config/nix-env/hooks/pre-setup.d/ |
NIX_ENV_VERSION, NIX_ENV_PLATFORM, ENV_DIR |
| Post-setup | ~/.config/nix-env/hooks/post-setup.d/ |
All above + NIX_ENV_SCOPES |
Overlay hooks in overlays/<name>/hooks/post-setup.d/ run after the per-machine post-setup hooks, and only for an
overlay subscribed from a local folder - one fetched from git never runs hooks. Each runs as its own bash process with ENV_DIR, NIX_ENV_PLATFORM and NIX_ENV_SCOPES set,
and with PATH covering the nix profile, ~/.local/bin, fnm's default Node and ~/google-cloud-sdk/bin, so it can call npm,
uv or gcloud, and with the shell's trust-store variables (NODE_EXTRA_CA_CERTS, SSL_CERT_FILE, ...) when ~/.config/certs holds the certificates. A hook that fails prints a warning and setup finishes. Overlays have no pre-setup hooks.
Hooks run on every setup run, so make them safe to repeat:
# overlays/<name>/hooks/post-setup.d/npm-globals.sh
v=5.6.3
npm ls -g "typescript@$v" >/dev/null 2>&1 || npm install -g "typescript@$v"
Deleting a hook stops it running; what it installed stays.
Example use cases:
- VPN check - verify VPN is connected before setup downloads packages
- Fleet telemetry - POST
install.jsonto a monitoring endpoint after setup - Team pinning - write
pinned_revto lock package versions across a team - Compliance - verify required scopes are present, block setup if missing
Pinning package versions¤
By default, nx upgrade moves to the CI-validated nixpkgs-unstable revision - a deterministic snapshot of 100k+ packages at specific versions. Each commit is a reproducible state, not a rolling release.
For teams that need coordinated versions:
nx upgrade # upgrade and verify everything works
nx pin set # pin the current (tested) revision
nx pin show # show current pin
nx pin remove # go back to the validated revision
The pin is stored in ~/.config/nix-env/pinned_rev. When present, nx upgrade locks to that commit instead of the validated revision. Set the pin from a pre-setup hook on each machine (placed there by your device management, for example):
# ~/.config/nix-env/hooks/pre-setup.d/pin_nixpkgs.sh
echo "abc123..." > "$HOME/.config/nix-env/pinned_rev"
When IT validates a new nixpkgs revision, they update the hook - every machine gets the tested baseline on its next setup run.
Upgrades and rollback¤
nx upgrade # upgrade all packages to latest (or pinned) versions
nx rollback # revert to the previous package set
nix profile diff-closures # see exactly what changed
nx gc # clean up old generations
Upgrades are atomic - all packages upgrade together through a single buildEnv. Rollback reverts the entire environment to the previous state, not individual packages. This eliminates partial upgrade states.
Quick reference¤
| Task | Command |
|---|---|
| Add a package | nx install <pkg> |
| Remove a package | nx remove <pkg> |
| List all packages | nx list |
| Search nixpkgs | nx search <term> |
| Create a scope with packages | nx scope add <name> <pkg> [pkg...] |
| Edit a scope file | nx scope edit <name> |
| Show scope tree | nx scope tree |
| Show overlays and sync state | nx overlay |
| Upgrade packages | nx upgrade |
| Pin current revision | nx pin set |
| Show / remove pin | nx pin show / nx pin remove |
| Roll back last upgrade | nx rollback |
| See what changed | nix profile diff-closures |
| Clean up old generations | nx gc |
| Run health checks | nx doctor |