Package: nixtract-cli
nixtractA CLI tool to extract the graph of derivations from a Nix flake.UsageRequirementsNix >= 2.4experimental featurenix-commandneeds to be enabled:Nix command - NixOS Wikiexperimental featureflakesneeds to be enabled:Flakes - NixOS WikiSet upGet it using Nix$nixshellgithub:tweag/nixtractor install in your Python environment:$pipinstallgit+https://github.com/tweag/nixtract.gitUsage$nixtract--helpUsage: nixtract [OPTIONS] OUTFILEExtract the graph of derivations from a flake as JSONL.OUTFILE is the path to the output file to write to, use "-" to write tostdout.Options:--target-flake-ref TEXT       The reference of the target Nix Flake--target-attribute-path TEXT  The attribute path of the providedattribute set to evaluate. If empty, theentire attribute set is evaluated--target-system TEXT          The system in which to evaluate thederivations--n-workers INTEGER           Count of workers to spawn to describe thestream of found derivations--offline                     Pass --offline to Nix commands-v, --verbose                 Increase verbosity--help                        Show this message and exit.Extract nixpkgs graph of derivationsTo extract the data from thenixpkgsof your flake registry and output to stdout, use:$nixtract-you can specify a file path directly instead$nixtractderivations.jsonlin order to extract from a specific flake, use--target-flake-ref:$nixtract--target-flake-ref'github:nixos/nixpkgs/23.05'-in order to extract from a specific attribute, use--target-attribute:$nixtract--target-attribute-path'haskellPackages.hello'-in order to extract for a specific system, use--target-system:$nixtract--target-system'x86_64-darwin'-Understanding the outputnixtractevaluates Nix code to recursively find all derivations in a flake.
It first finds the top level derivations, basically all derivations you can find withnix search.
Then it recurses into the input derivations of any derivation it has found.Each line of the output is a valid JSON that describes a derivation.
As such, the output is a JSONL file.The JSON schema of a derivation can be shown like so:$python-c'import nixtract.model; print(nixtract.model.Derivation.schema_json(indent=2))'DevelopmentSet upRequires a Python environment (^3.10) andpoetry.$poetryinstallUnder the hoodThe overall architecture inside is described innixtract/cli.py:Calling this tool starts a subprocess that list top-level derivations (outputPath + attribute path) to its stderr pipe, see `./find-attribute-paths.nix`.
This pipe is consumed in a thread (`finder_output_reader`) that reads each line and feeds found attribute paths to a queue.
This queue is consumed by another thread (`queue_processor`) that will call a subprocess that describes the derivation (name, version, license, dependencies, ...), see `./describe-derivation.nix`.
When describing a derivation, if dependencies are found and have not been already queued for processing, they are added to the queue as well, which makes us explore the entire depth of the graph.

The whole system stops once
- all top-level attribute paths have been found
- all derivations from that search have been processed
- all dependencies have been processed

Glossary:
- output path: full path of the realization of the derivation in the Nix store.
               e.g. /nix/store/py9jjqsgsya5b9cpps64gchaj8lq2h5i-python3.10-versioneer-0.28
- attribute path: path from the root attribute set to get the desired value.
                  e.g. python3Derivations.versioneer