nixtract
A CLI tool to extract the graph of derivations from a Nix flake.
Usage
Requirements
- Nix >= 2.4
- experimental feature
nix-commandneeds to be enabled: Nix command - NixOS Wiki - experimental feature
flakesneeds to be enabled: Flakes - NixOS Wiki
- experimental feature
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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.