fix

fix is a fast, parallel evaluator and command-line tool for the Nix language, written in Zig.

It is a from-scratch implementation, not a wrapper around the Nix evaluator. fix parses Nix source, compiles it to bytecode, evaluates expressions lazily, computes derivations and store paths, and speaks the Nix daemon protocol for store operations and builds. It is intended to run existing Nix expressions and produce the same values and derivations while making evaluation faster.

fix also treats the evaluator as something you should be able to inspect. It includes a heap and bytecode explorer, a source-level debugger, an interactive REPL, evaluation statistics, and Perfetto-compatible traces.

fix can evaluate thunk work on multiple worker threads. A thunk contains a Future: one fiber claims an unresolved thunk, while another fiber that reaches the same in-flight thunk can park and let its worker run something else. Speculative forcing and strict-demand fan-out provide work for otherwise idle workers; both can be disabled when diagnosing parallel behavior.

The worker count is configurable, including a single-worker mode when repeatability or debugging matters more than throughput. Memory is managed by a parallel generational garbage collector.

The core concurrency protocols — future wait, fiber dispatch, shutdown, and the GC barrier — are modeled in TLA+ and checked for safety, deadlock freedom, and liveness. A nightly CI lane evaluates real configurations in parallel against a reference Nix under ThreadSanitizer.

Compatibility is a target backed by several kinds of tests:

• Derivation tests cover canonical ATerm serialization, hashing, string context, and expected .drv and output store paths.
• The pinned Lix and snix language suites compare evaluation and parse results.
• A separate differential test evaluates every benchmark fixture with fix and a reference Nix, then compares the strict JSON results structurally.
• A whole-nixpkgs differential evaluates the entire nixpkgs CI job universe (ci/eval/outpaths.nix, about 80,000 derivations) with fix and a reference Nix and compares every .drv store path. A drvPath match certifies the complete derivation that produced it — inputs, environment, and builder, transitively.
• fix parse emits the same JSON-shaped syntax tree used by nix-instantiate --parse.

The language suites and nixpkgs derivation-path differential are separate checks, with their scope described in the language-test documentation. The nixpkgs differential runs monolithically with zig build test-nixpkgs (it wants a large-memory machine and caches the reference results per pin) and as a sharded matrix in CI.

The VM explorer and debugger are part of fix, rather than separate instrumented builds. They operate on the real compiler, bytecode, stacks, thunks, and heap used by ordinary evaluations.

The explorer can move from source expressions to compiled chunks and instructions, inspect heap objects and their references, search stores, and set breakpoints. Large chunk and object collections are represented with range nodes and bounded queries rather than one UI row per entry.

The debugger supports:

• pending and resolved source-line breakpoints;
• builtins.break and stops on evaluation errors;
• step, next, finish, and continue;
• lexical locals, captured values, the operand stack, and annotated bytecode;
• evaluating a Nix expression in the scope of the current pause; and
• opening the VM explorer without leaving the debugging session.

fix eval --debugger and fix repl --debugger use one worker. A transient :debug session in an ordinary REPL temporarily disables parallel submissions.

This demo first evaluates a NixOS toplevel, then starts a debugger session while that evaluation's heap remains available to inspect.

fix is alpha-quality software under active development. The development environment is exercised on x86_64 Linux; other platforms have received less testing.

Nix is not required to build fix. A direct build requires Zig 0.16, pkg-config, libcurl, and libgit2:

$ git clone https://github.com/psyclyx/fix
$ cd fix
$ zig build --release=fast

The executable is zig-out/bin/fix. Alternatively, Nix can provide the pinned build environment and dependencies:

$ nix-shell --run 'zig build --release=fast'

Evaluation does not require a Nix or Lix executable. Store-writing commands need a reachable Nix or Lix daemon.

$ ./zig-out/bin/fix eval -E '1 + 2'
3

$ ./zig-out/bin/fix build -A fix

$ ./zig-out/bin/fix repl

The package also includes shell completions for Bash, Fish, and Zsh.

fix speaks the stable Nix worker protocol to CppNix and Lix daemons (Nix ≥ 2.4) over daemon, unix://, tcp://, and ssh-ng:// stores. local/auto stores and Lix's experimental lix-xp-1 protocol are not implemented and fail explicitly — nothing falls back to an installed Nix. The selector matrix and configuration details are in Nix/Lix store compatibility.

<nixpkgs> and other lookup paths resolve like Nix's: from -I, then $NIX_PATH, and — when neither is set — from the user and root channel profiles, so a machine configured purely through nix-channel works without any environment setup.

builtins.nixVersion deliberately reports 2.18.3: it is the evaluator compatibility baseline, not the version of the connected daemon. Supported experimental and deprecated language switches are listed in the CLI reference.

fix covers the common path from evaluating an expression to realizing and running its output:

Run fix <command> --help for the documented inputs and options.

Commands accept expressions, file paths, attribute paths, and repeated mixed inputs. File paths are positional, and omitting the source uses ./default.nix:

$ fix eval -E '{ answer = 6 * 7; }' -A answer
42

$ fix eval --strict --json packages.nix

$ fix instantiate -A fix
/nix/store/...-fix.drv

$ fix build -A fix

Arguments can be supplied with --arg and --argstr. Evaluation can produce Nix, JSON, XML, or raw output, and can be made strict. Builds can target direct Unix-socket, SSH, and TCP daemon endpoints.

$ fix run --flake nixpkgs#hello

$ fix shell -p ripgrep jq

fix run builds the selected installable and chooses its executable from meta.mainProgram, pname, or name. fix shell constructs and realizes an environment containing the requested packages.

Flake commands require Nix's flakes experimental feature. Enable it in nix.conf, or pass it for an invocation:

$ fix flake show . --extra-experimental-features flakes

fix print-dev-env evaluates a derivation and prints a Bash program that reconstructs its build environment without building the derivation:

$ eval "$(fix print-dev-env ./shell.nix)"

The included direnv integration provides use fix and use fix_flake. See the direnv documentation for installation and options.

fix switch can build and activate NixOS configurations and implements the conventional nix-darwin and Home Manager activation paths. It supports switch, boot, test, build, and dry-activate actions. When supplied, the action must be the first argument after fix switch.

$ fix switch --nixos

$ fix switch build --home-manager --flake .#me

This command is experimental. Its scope and interface may change; do not use it as a stable automation interface.

Start the REPL with fix repl. From there:

• :vm opens the full-screen VM explorer;
• :d EXPR evaluates an expression in the debugger; and
• :help lists the available REPL commands.

The debugger can also be enabled directly on an evaluation:

$ fix eval --debugger ./expression.nix

Inside the debugger, break FILE:LINE adds a source breakpoint. A breakpoint may remain pending until that source is compiled; it resolves automatically when the matching code appears. breakpoints lists breakpoints and delete N removes one. :gc runs a full collection while preserving the paused session's values and refreshes the heap views.

Both tools also have bounded text output for non-interactive use. Start the REPL with fix repl --no-tui when an alternate-screen interface is undesirable.

The chart and tables are point-in-time measurements from pinned inputs, not a claim that fix wins every workload. They compare wall-clock evaluation time across synthetic stress tests, real NixOS and Home Manager configurations, and JSON-producing workloads. Each cell is relative to the fastest evaluator for that workload; 1.00× is fastest. The harness defaults to five recorded runs.

The timing harness uses Hyperfine, with separate warmup and measured runs and optional cache reclamation between runs. Correctness is checked separately by zig build test-bench-fixtures; it is not part of the timing script. See the benchmark documentation for the workloads and reproduction commands.

fix runs nixboy, a Game Boy emulator written in Nix.

The repository exports modules for NixOS, nix-darwin, and Home Manager:

let
  fixSource = /path/to/a/pinned/fix;
  fixProject = import fixSource {};
in {
  imports = [
    fixProject.homeManagerModules.fix
  ];

  programs.fix.enable = true;
}

Use nixosModules.fix or darwinModules.fix in the corresponding module system. Enabling programs.direnv enables the bundled integration by default and installs fix; it can be controlled explicitly with programs.direnv.fix.enable. Use programs.fix.enable when you want the CLI without direnv.

fix is alpha-quality software under active development. Compatibility is a concrete target backed by focused and differential tests, but not a promise that every Nix program or workflow is supported. A Nix or Lix daemon is needed for store operations and builds; it need not be supplied by a locally installed Nix executable.

If fix produces a different value, derivation, or store path from Nix for supported input, that is a bug. Releases are documented in the changelog.

Enter the pinned development environment and build an optimized binary with:

$ nix-shell --run 'zig build --release=fast'

The result is zig-out/bin/fix. Useful checks include:

$ zig build test
$ zig build check
$ zig build test-lang
$ zig build test-bench-fixtures
$ zig build test-nixpkgs

Start with the developer documentation for the architecture, runtime invariants, testing strategy, and performance model.