liminfoNix/NixOS Reference
Free reference guide: Nix/NixOS Reference
About Nix/NixOS Reference
The Nix / NixOS Reference covers the modern Nix ecosystem centered around Flakes, which became the recommended workflow for reproducible builds and development environments. The CLI section documents the core nix commands: nix build for compiling packages from a flake output, nix develop for entering a reproducible development shell, nix run for executing a package without installing it, nix shell for temporarily adding packages to PATH, nix profile install for user-level package management, and nix search for querying nixpkgs. These commands replace the older nix-env, nix-build, and nix-shell workflows.
The Flake section explains the flake.nix structure with inputs and outputs, how to pin nixpkgs to a specific channel such as nixos-unstable, and how to define packages and devShells for multiple system architectures. nix flake update and nix flake lock are documented for managing the flake.lock file that pins every dependency to an exact commit hash for bit-perfect reproducibility. The Packages section covers stdenv.mkDerivation for building from source, buildInputs for runtime dependencies, nativeBuildInputs for build-time host tools like cmake and pkg-config, and override / overlays for customizing existing packages.
NixOS system management and Home Manager round out the reference. The nixos-rebuild commands (switch, test, boot) explain how to atomically apply system configuration changes with rollback support. The configuration.nix section shows how to enable services, declare system packages using environment.systemPackages, and open firewall ports declaratively. Home Manager entries demonstrate how to manage user dotfiles and programs like zsh, git, tmux, and starship in a reproducible, version-controlled way. This reference is used by systems engineers, Nix enthusiasts adopting declarative infrastructure, and developers building reproducible CI pipelines.
Key Features
- Core Nix CLI — nix build, nix develop, nix run, nix shell, nix profile install, nix search
- flake.nix structure — inputs, outputs, nixpkgs channel pinning, multi-arch devShells
- nix flake update and nix flake lock for reproducible dependency pinning
- stdenv.mkDerivation with buildInputs and nativeBuildInputs package build examples
- Package override and overlays for customizing nixpkgs derivations
- NixOS nixos-rebuild switch/test with declarative configuration.nix examples
- Declarative service enablement and firewall configuration in configuration.nix
- Home Manager programs.* declarations for zsh, git, tmux, starship, and more
Frequently Asked Questions
What is Nix and how is it different from other package managers?
Nix is a purely functional package manager that stores every package in an immutable path under /nix/store based on a cryptographic hash of all its inputs. This means multiple versions of the same package can coexist, installations are atomic and rollback-safe, and builds are reproducible across machines. Unlike apt or brew, Nix never mutates shared library directories, so installing or upgrading one package cannot break another.
What are Nix Flakes and why should I use them?
Flakes are the modern standard for composing Nix projects. A flake.nix file declares inputs (other flakes, like nixpkgs) and outputs (packages, dev shells, NixOS configurations). A companion flake.lock file pins every input to an exact git commit hash, making builds perfectly reproducible across different machines and over time. Flakes also enforce a standard output schema, making it easy to consume packages from third-party repos with nix run github:user/repo.
What is the difference between buildInputs and nativeBuildInputs?
buildInputs lists packages that the derivation needs at runtime on the target platform — for example, a shared library like openssl that the compiled binary will link against. nativeBuildInputs lists tools that run on the host during the build process — such as cmake, pkg-config, or a code generator. This distinction matters for cross-compilation: native tools must run on the build machine, while regular inputs must be compiled for the target architecture.
How does nixos-rebuild switch work?
nixos-rebuild switch reads your /etc/nixos/configuration.nix (or a flake), builds the new system configuration as a derivation, activates it immediately by switching symlinks, and registers it as a boot entry. The previous configuration remains available for rollback. nixos-rebuild test activates the configuration without making it the default boot entry — useful for testing changes before committing them. All changes are atomic: either the full new config is applied or the system stays as-is.
What is Home Manager and how does it relate to NixOS?
Home Manager is a Nix-based tool for managing user-level configuration files and packages declaratively. While NixOS manages system-wide services and packages via configuration.nix, Home Manager handles per-user programs, dotfiles, and shell configurations. It can be used as a NixOS module (sharing the same nixpkgs), as a standalone tool on non-NixOS Linux, or on macOS. Programs like zsh, git, tmux, and neovim have dedicated Home Manager modules with structured options instead of raw dotfiles.
How do I create a reproducible development environment with Nix Flakes?
Define a devShells.${system}.default output in your flake.nix using pkgs.mkShell with a packages list. Running nix develop will drop you into a shell with exactly those tools available, regardless of what is installed system-wide. The flake.lock ensures every teammate and every CI run gets identical tool versions. You can also use direnv with nix-direnv so the dev shell activates automatically when you cd into the project directory.
How do Nix overlays work?
Overlays are functions that take the final and previous package sets and return an attribute set of overrides or additions. You add an overlay to nixpkgs by passing it in the overlays argument when importing nixpkgs. This lets you replace a package with a patched version, add a new package not in nixpkgs, or modify package attributes like version or build flags globally. Overlays compose cleanly because each overlay sees the result of all previous overlays.
Can I use Nix on macOS?
Yes. Nix runs on macOS via the Nix package manager installed with the Determinate Systems installer or the official installer. You can use nix develop, nix shell, and nix run just like on Linux. Home Manager also works on macOS. For a full system-level declarative macOS setup similar to NixOS, nix-darwin provides a configuration.nix-style module system for managing macOS system preferences, Homebrew packages, and launch daemons.