# nixos/nix architecture

> Architecture diagram of the GitHub repository nixos/nix, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nixos/nix
- Repository: https://github.com/nixos/nix

## Overview

#### Purpose and entry points
Nix is a C++ package manager implementing the Nix language, dependency evaluation, reproducible builds, and content-addressed store management. The primary executable is the modern `nix` CLI, rooted at `src/nix/main.cc` and composed from command implementations in `src/nix/`. Legacy compatibility executables (`nix-build`, `nix-store`, `nix-env`, etc.) remain separate entry points under `src/nix/nix-build/nix-build.cc`, `src/nix/nix-store/nix-store.cc`, and related directories.

#### Command and runtime layer
`libmain` provides shared process initialization, logging, progress, common options, and plugin loading; `libcmd` supplies command registration, installable resolution, REPL integration, store flags, and CLI evaluation arguments.
- `src/libmain/shared.cc`
- `src/libcmd/command.cc`
- `src/nix/build.cc`

Commands convert user arguments, installable/flake references, and configuration into evaluator or store operations. The CLI boundary is also where structured output, progress reporting, and daemon-aware store selection are applied.

#### Nix language evaluation
`libexpr` implements the Nix lexer/parser, lazy value model, evaluator, primops, derivation extraction, and evaluation cache. Nix expressions evaluate to values that may describe derivations, paths, or flake outputs; derivation-producing primitives bridge evaluation into the store model.
- `src/libexpr/lexer.l`
- `src/libexpr/parser.y`
- `src/libexpr/eval.cc`
- `src/libexpr/primops.cc`

The C API layer exposes evaluator functionality to external consumers without requiring direct C++ linkage: `src/libexpr-c/nix_api_eval.cc`.

#### Flakes and source acquisition
Flakes add reproducible input resolution and lockfile handling over the evaluator. `libflake` parses flake references, reads/writes lock files, evaluates flake outputs, and installs flake-specific primops. `libfetchers` obtains source trees and archives and can materialize them into a store.
- `src/libflake/flake.cc`
- `src/libflake/lockfile.cc`
- `src/libfetchers/fetchers.cc`
- `src/libfetchers/fetch-to-store.cc`

Fetcher backends cover local paths, Git/Git LFS, Mercurial, tarballs, and GitHub (`src/libfetchers/git.cc`, `src/libfetchers/github.cc`). These are network and filesystem trust boundaries.

#### Store model and persistence
`libstore` owns store paths, derivations, content addressing, references, realizations, garbage collection, import/export, and the abstract store API. Local-store metadata is backed by SQLite schemas, while store implementations can be local, overlay, HTTP cache, S3, SSH, or remote-daemon based.
- `src/libstore/store-api.cc`
- `src/libstore/local-store.cc`
- `src/libstore/schema.sql`
- `src/libstore/derivation/resolution.cc`
- `src/libstore/s3-binary-cache-store.cc`

Store protocols and serialized data are compatibility-critical boundaries: `src/libstore/worker-protocol.cc`, `src/libstore/serve-protocol.cc`, and documented JSON schemas under `doc/manual/source/protocols/json/schema/`.

#### Build, substitution, and daemon execution
The build worker schedules dependency goals, resolves derivations, tries substituters, and dispatches local or remote building. Platform-specific derivation builders enforce execution isolation; Linux uses chroot/namespaces-oriented machinery, with Darwin, FreeBSD, and Windows implementations separated.
- `src/libstore/build/worker.cc`
- `src/libstore/build/derivation-goal.cc`
- `src/libstore/build/substitution-goal.cc`
- `src/libstore/linux/build/linux-derivation-builder.cc`
- `src/libstore/unix/build/chroot-derivation-builder.cc`

The multi-user daemon serves store requests over Unix-domain sockets, with service definitions for systemd, launchd, System V, and Upstart. Relevant paths: `src/libstore/daemon.cc`, `src/nix/unix/daemon.cc`, `misc/systemd/nix-daemon.service.in`.

#### Build, distribution, and verification
Meson is the native C++ build graph root (`meson.build`); Nix expressions provide reproducible packaging, development shells, installers, release jobs, and CI integration (`flake.nix`, `packaging/everything.nix`, `packaging/installer/install.in`). The project targets Unix-like systems plus active platform-specific Windows support.

Validation spans library unit tests, protocol/schema checks, and end-to-end functional/NixOS scenarios, particularly around evaluation, daemon behavior, sandboxing, remote builds, fetchers, and binary caches. Core integration suites live in `tests/functional/`, while deployment-oriented tests live in `tests/nixos/`.

Main entry points: [`src/libstore/store-api.cc`](https://github.com/nixos/nix/blob/master/src/libstore/store-api.cc) (libstore API), [`src/libexpr/eval.cc`](https://github.com/nixos/nix/blob/master/src/libexpr/eval.cc) (libexpr evaluator), [`src/nix/build.cc`](https://github.com/nixos/nix/blob/master/src/nix/build.cc) (Build command), [`src/libstore/build/worker.cc`](https://github.com/nixos/nix/blob/master/src/libstore/build/worker.cc) (Build worker)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI &amp; APIs"]
  node_nix_cli["nix CLI<br/>executable<br/>[main.cc]"]
  node_legacy_cli["Legacy CLIs<br/>executables<br/>[nix-build.cc]"]
  node_libmain["libmain runtime<br/>runtime library<br/>[shared.cc]"]
  node_libcmd["libcmd<br/>command library<br/>[command.cc]"]
  node_build_command["Build command<br/>CLI command<br/>[build.cc]"]
  node_c_eval_api["C evaluator API<br/>C API<br/>[nix_api_eval.cc]"]
end

subgraph group_evaluation["Evaluation &amp; flakes"]
  node_nix_parser["Lexer &amp; parser<br/>language frontend<br/>[parser.y]"]
  node_evaluator["libexpr evaluator<br/>lazy evaluator<br/>[eval.cc]"]
  node_flakes["libflake<br/>flake resolver<br/>[flake.cc]"]
  node_fetchers["libfetchers<br/>source acquisition<br/>[fetch-to-store.cc]"]
end

subgraph group_store["Store &amp; execution"]
  node_store_api["libstore API<br/>store abstraction<br/>[store-api.cc]"]
  node_local_store[("Local store<br/>store implementation<br/>[local-store.cc]")]
  node_store_backends["Remote store backends<br/>store implementations"]
  node_build_worker["Build worker<br/>scheduler<br/>[worker.cc]"]
  node_substitution["Substitution goals<br/>binary cache flow"]
  node_sandbox_builder["Sandboxed builder<br/>platform builder"]
  node_daemon{{"Nix daemon<br/>multi-user service<br/>[daemon.cc]"}}
end

subgraph group_distribution["Build &amp; deployment"]
  node_meson["Meson build graph<br/>native build<br/>[meson.build]"]
  node_nix_packaging["Nix packaging &amp; CI<br/>reproducible packaging<br/>[flake.nix]"]
  node_daemon_service["Daemon service unit<br/>service definition"]
end

node_nix_cli -->|"initializes with"| node_libmain
node_nix_cli -->|"dispatches"| node_libcmd
node_legacy_cli -->|"uses"| node_store_api
node_libcmd -->|"registers"| node_build_command
node_build_command -->|"evaluates inputs"| node_evaluator
node_build_command -->|"requests builds"| node_store_api
node_c_eval_api -->|"exposes"| node_evaluator
node_nix_parser -->|"parses expressions for"| node_evaluator
node_flakes -->|"evaluates outputs with"| node_evaluator
node_flakes -->|"resolves inputs through"| node_fetchers
node_fetchers -->|"materializes sources in"| node_store_api
node_evaluator -->|"produces derivations for"| node_store_api
node_store_api -->|"implemented by"| node_local_store
node_store_api -->|"implemented by"| node_store_backends
node_store_api -->|"executes builds via"| node_build_worker
node_build_worker -->|"tries"| node_substitution
node_build_worker -->|"dispatches local builds to"| node_sandbox_builder
node_daemon -->|"serves"| node_store_api
node_daemon_service -->|"launches"| node_daemon
node_nix_packaging -->|"packages native build"| node_meson

click node_nix_cli "https://github.com/nixos/nix/blob/master/src/nix/main.cc"
click node_legacy_cli "https://github.com/nixos/nix/blob/master/src/nix/nix-build/nix-build.cc"
click node_libmain "https://github.com/nixos/nix/blob/master/src/libmain/shared.cc"
click node_libcmd "https://github.com/nixos/nix/blob/master/src/libcmd/command.cc"
click node_build_command "https://github.com/nixos/nix/blob/master/src/nix/build.cc"
click node_c_eval_api "https://github.com/nixos/nix/blob/master/src/libexpr-c/nix_api_eval.cc"
click node_nix_parser "https://github.com/nixos/nix/blob/master/src/libexpr/parser.y"
click node_evaluator "https://github.com/nixos/nix/blob/master/src/libexpr/eval.cc"
click node_flakes "https://github.com/nixos/nix/blob/master/src/libflake/flake.cc"
click node_fetchers "https://github.com/nixos/nix/blob/master/src/libfetchers/fetch-to-store.cc"
click node_store_api "https://github.com/nixos/nix/blob/master/src/libstore/store-api.cc"
click node_local_store "https://github.com/nixos/nix/blob/master/src/libstore/local-store.cc"
click node_store_backends "https://github.com/nixos/nix/blob/master/src/libstore/s3-binary-cache-store.cc"
click node_build_worker "https://github.com/nixos/nix/blob/master/src/libstore/build/worker.cc"
click node_substitution "https://github.com/nixos/nix/blob/master/src/libstore/build/substitution-goal.cc"
click node_sandbox_builder "https://github.com/nixos/nix/blob/master/src/libstore/linux/build/linux-derivation-builder.cc"
click node_daemon "https://github.com/nixos/nix/blob/master/src/libstore/daemon.cc"
click node_meson "https://github.com/nixos/nix/blob/master/meson.build"
click node_nix_packaging "https://github.com/nixos/nix/blob/master/flake.nix"
click node_daemon_service "https://github.com/nixos/nix/blob/master/misc/systemd/nix-daemon.service.in"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_nix_cli,node_legacy_cli,node_libmain,node_libcmd,node_build_command,node_c_eval_api toneBlue
class node_nix_parser,node_evaluator,node_flakes,node_fetchers toneAmber
class node_store_api,node_local_store,node_store_backends,node_build_worker,node_substitution,node_sandbox_builder,node_daemon toneMint
class node_meson,node_nix_packaging,node_daemon_service toneRose
```

## Components

### CLI & APIs

- [nix CLI](https://github.com/nixos/nix/blob/master/src/nix/main.cc): executable · Modern command-line entry point. · `src/nix/main.cc`
- [Legacy CLIs](https://github.com/nixos/nix/blob/master/src/nix/nix-build/nix-build.cc): executables · Compatibility commands such as nix-build and nix-store. · `src/nix/nix-build/nix-build.cc`
- [libmain runtime](https://github.com/nixos/nix/blob/master/src/libmain/shared.cc): runtime library · Initializes processes, logging, options, progress, and plugins. · `src/libmain/shared.cc`
- [libcmd](https://github.com/nixos/nix/blob/master/src/libcmd/command.cc): command library · Registers commands and resolves installables. · `src/libcmd/command.cc`
- [Build command](https://github.com/nixos/nix/blob/master/src/nix/build.cc): CLI command · `src/nix/build.cc`
- [C evaluator API](https://github.com/nixos/nix/blob/master/src/libexpr-c/nix_api_eval.cc): C API · External evaluator interface. · `src/libexpr-c/nix_api_eval.cc`

### Evaluation & flakes

- [Lexer & parser](https://github.com/nixos/nix/blob/master/src/libexpr/parser.y): language frontend · `src/libexpr/parser.y`
- [libexpr evaluator](https://github.com/nixos/nix/blob/master/src/libexpr/eval.cc): lazy evaluator · Values, primops, derivation extraction, and evaluation cache. · `src/libexpr/eval.cc`
- [libflake](https://github.com/nixos/nix/blob/master/src/libflake/flake.cc): flake resolver · Resolves inputs and lockfiles, then evaluates flake outputs. · `src/libflake/flake.cc`
- [libfetchers](https://github.com/nixos/nix/blob/master/src/libfetchers/fetch-to-store.cc): source acquisition · Fetches source trees and materializes them in the store. · `src/libfetchers/fetch-to-store.cc`

### Store & execution

- [libstore API](https://github.com/nixos/nix/blob/master/src/libstore/store-api.cc): store abstraction · Content-addressed paths, derivations, references, and realizations. · `src/libstore/store-api.cc`
- [Local store](https://github.com/nixos/nix/blob/master/src/libstore/local-store.cc): store implementation · Persists local metadata in SQLite. · `src/libstore/local-store.cc`
- [Remote store backends](https://github.com/nixos/nix/blob/master/src/libstore/s3-binary-cache-store.cc): store implementations · HTTP cache, S3, SSH, overlay, and daemon-backed stores. · `src/libstore/s3-binary-cache-store.cc`
- [Build worker](https://github.com/nixos/nix/blob/master/src/libstore/build/worker.cc): scheduler · Schedules goals and dispatches builds or substitutions. · `src/libstore/build/worker.cc`
- [Substitution goals](https://github.com/nixos/nix/blob/master/src/libstore/build/substitution-goal.cc): binary cache flow · `src/libstore/build/substitution-goal.cc`
- [Sandboxed builder](https://github.com/nixos/nix/blob/master/src/libstore/linux/build/linux-derivation-builder.cc): platform builder · Linux build isolation uses chroot and namespace machinery. · `src/libstore/linux/build/linux-derivation-builder.cc`
- [Nix daemon](https://github.com/nixos/nix/blob/master/src/libstore/daemon.cc): multi-user service · Serves store requests over Unix-domain sockets. · `src/libstore/daemon.cc`

### Build & deployment

- [Meson build graph](https://github.com/nixos/nix/blob/master/meson.build): native build · `meson.build`
- [Nix packaging & CI](https://github.com/nixos/nix/blob/master/flake.nix): reproducible packaging · Defines packages, development shells, installers, releases, and CI. · `flake.nix`
- [Daemon service unit](https://github.com/nixos/nix/blob/master/misc/systemd/nix-daemon.service.in): service definition · `misc/systemd/nix-daemon.service.in`

## Connections

- nix CLI → libmain runtime: initializes with
- nix CLI → libcmd: dispatches
- Legacy CLIs → libstore API: uses
- libcmd → Build command: registers
- Build command → libexpr evaluator: evaluates inputs
- Build command → libstore API: requests builds
- C evaluator API → libexpr evaluator: exposes
- Lexer & parser → libexpr evaluator: parses expressions for
- libflake → libexpr evaluator: evaluates outputs with
- libflake → libfetchers: resolves inputs through
- libfetchers → libstore API: materializes sources in
- libexpr evaluator → libstore API: produces derivations for
- libstore API → Local store: implemented by
- libstore API → Remote store backends: implemented by
- libstore API → Build worker: executes builds via
- Build worker → Substitution goals: tries
- Build worker → Sandboxed builder: dispatches local builds to
- Nix daemon → libstore API: serves
- Daemon service unit → Nix daemon: launches
- Nix packaging & CI → Meson build graph: packages native build
