Skip to main content

nixtract

A CLI tool to extract the graph of derivations from a Nix flake.

Usage

Requirements

Set up

Get it using Nix

$ nix shell github:tweag/nixtract

or install in your Python environment:

$ pip install git+https://github.com/tweag/nixtract.git

Usage

$ nixtract --help
Usage: nixtract [OPTIONS] OUTFILE

  Extract the graph of derivations from a flake as JSONL.

  OUTFILE is the path to the output file to write to, use "-" to write to
  stdout.

Options:
  --target-flake-ref TEXT       The reference of the target Nix Flake
  --target-attribute-path TEXT  The attribute path of the provided
                                attribute set to evaluate. If empty, the
                                entire attribute set is evaluated
  --target-system TEXT          The system in which to evaluate the
                                derivations
  --n-workers INTEGER           Count of workers to spawn to describe the
                                stream of found derivations
  --offline                     Pass --offline to Nix commands
  -v, --verbose                 Increase verbosity
  --help                        Show this message and exit.

Extract nixpkgs graph of derivations

To extract the data from the nixpkgs of your flake registry and output to stdout, use:

$ nixtract -

you can specify a file path directly instead

$ nixtract derivations.jsonl

in 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 output

nixtract evaluates Nix code to recursively find all derivations in a flake. It first finds the top level derivations, basically all derivations you can find with nix 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))'

Development

Set up

Requires a Python environment (^3.10) and poetry.

$ poetry install

Under the hood

The overall architecture inside is described in nixtract/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

Metadata

Release files for nixtract-cli 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for nixtract-cli 0.1.0
File Size Uploaded Provenance Actions
nixtract_cli-0.1.0.tar.gz 11.4 kB Without provenance Details for nixtract_cli-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for nixtract-cli 0.1.0
File Interpreter ABI Platform Actions
nixtract_cli-0.1.0-py3-none-any.whl Python 3 none any Details for nixtract_cli-0.1.0-py3-none-any.whl

Total release size: 24.9 kB

Release files / nixtract_cli-0.1.0.tar.gz

Download URL nixtract_cli-0.1.0.tar.gz
Size 11.4 kB
Tags Source
SHA-256 checksum
How to use checksums
e832755107d4a232f9dd80a20f1c0e664e1d1fe17e4abd0154a04ba11f4b3e10
BLAKE2b-256 checksum
How to use checksums
d52b894ba63ec17114cec5109a5a9fe06828f8eba3c3eb55d735962c4b7fb814
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via poetry/1.7.1 CPython/3.12.0 Linux/6.5.11-300.fc39.x86_64

Release files / nixtract_cli-0.1.0-py3-none-any.whl

Download URL nixtract_cli-0.1.0-py3-none-any.whl
Size 13.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
be696f0fc2dd9feda829cbb320ec98bfc6c87d14d3fe0e74e00e87d00771c28f
BLAKE2b-256 checksum
How to use checksums
9266e7c82e7d14b817e5620e0b5ca9d4f64759fddb8c3039f8ed87f343951c1b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via poetry/1.7.1 CPython/3.12.0 Linux/6.5.11-300.fc39.x86_64

Security for nixtract-cli 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page