pixi-sbom

Generates a Software Bill of Materials (SBOM) from a lockfile — pixi.lock, uv.lock, pylock.toml, poetry.lock, pdm.lock, conda-lock.yml or an explicit conda spec — or from an installed conda environment or venv, as CycloneDX 1.6 / 1.7 or SPDX 2.3 / 3.0.1 JSON. A pixi extension (pixi sbom) that needs no pixi: the same binary runs as pixi-sbom, from PyPI with uvx pixi-sbom.

Full documentation: https://millsks.github.io/pixi-sbom/ What 1.0 freezes, and what it does not: stability.md Found a vulnerability? SECURITY.md says where to send it privately and what is in scope.

Each report has a recording of its own in the command-line reference: vulnerabilities, licenses, packages, diff, python, phantom, outdated, scorecard, quality, EPSS and a vendor's VEX.

What it does

What it is not: a scanner (it feeds one), a package manager, or a stable Rust library — the command line is the interface, and what 1.0 freezes says exactly which parts.

Installation

pixi global install pixi-sbom

Outside the conda ecosystem, uvx pixi-sbom runs it from PyPI without installing anything (or pip install pixi-sbom, uv tool install pixi-sbom), and cargo binstall pixi-sbom fetches the same release binary (cargo install pixi-sbom builds it from crates.io). Or download a binary from the releases page and put it on your PATH, or build from source:

pixi run build
cp target/release/pixi-sbom ~/.pixi/bin/

Pixi discovers any pixi-<name> executable on PATH and exposes it as pixi <name>; pixi --list shows it.

Every release archive from 0.11.0 onward is signed with build provenance. To check that a downloaded archive really was built by this repository, from the commit it claims, in a GitHub Actions run — not just that it arrived unchanged, which is all a checksum tells you:

gh attestation verify pixi-sbom-<version>-linux-64.tar.gz --repo millsks/pixi-sbom

A .sigstore.json bundle ships beside each archive for machines that cannot reach api.github.com: add --bundle pixi-sbom-<version>-linux-64.tar.gz.sigstore.json and the check runs offline. The strict form also pins the release workflow and the tag.

What it supports

A lockfile newer than this build understands is refused by name rather than half-read:

$ pixi sbom
Error: pixi_sbom::lock::parse
  × cannot read lockfile pixi.lock
  ╰─▶ found newer lockfile format version 8, but only up to including version 7 is supported
  help: this build reads pixi.lock up to version 7: run `pixi lock` to rewrite an older or
        damaged one, or upgrade pixi-sbom if the file's `version:` is higher

Without pixi

A uv, Poetry, PDM or conda-lock project needs nothing but the binary:

uvx pixi-sbom --lockfile uv.lock                            # from PyPI, nothing installed
pixi-sbom --lockfile poetry.lock --format spdx
pixi-sbom --prefix .venv --against uv.lock --report diff    # does the venv still match its lock?

See Using pixi-sbom without pixi for each lockfile kind, what works with which, and why a requirements.txt with ranges is not an input.

Quick start

# CycloneDX SBOM for the default environment on this platform,
# written next to pixi.lock as sbom.cdx.json
pixi sbom

# SPDX instead (sbom.spdx.json)
pixi sbom --format spdx

# Pipe into a scanner instead of writing a file
pixi sbom --output - | grype

# Licenses for every package, conda and PyPI alike (add --license-texts for the full texts)
pixi sbom --fetch-licenses

# Include what maturin compiled into the wheels (PEP 770 embedded SBOMs)
pixi sbom --embedded-sboms

# Fail CI on copyleft or unlicensed packages (exit code 3, document still written)
pixi sbom --fetch-licenses --deny-license GPL-3.0-only --require-license

# Known vulnerabilities from OSV, recorded in the document (conda packages match via their PyPI purl)
pixi sbom --pypi-mapping prefix --vulnerabilities osv

# ... or as a table, worst first
pixi sbom --pypi-mapping prefix --vulnerabilities osv --report vulnerabilities

# What changed since a previous document (added, removed, version and license changes),
# and fail the build when anything did
pixi sbom --report diff --against previous.cdx.json --report-format markdown
pixi sbom --report diff --against previous.cdx.json --fail-on-diff

# Does this container still match the lockfile? (pip installs and rebuilds included)
pixi sbom --prefix /opt/conda/envs/app --against pixi.lock --report diff --fail-on-diff

# How far behind the environment is: versions, ages, releases behind, patch/minor/major
pixi sbom --report outdated --outdated-min major

# Why the next Python is blocked: which packages cap the interpreter
pixi sbom --report python

# What the code imports but never declared, and what is declared but never imported
pixi sbom --report phantom

# Fail CI on anything high or critical, except a finding assessed as not affecting you (exit code 4)
pixi sbom --pypi-mapping prefix --vulnerabilities osv --fail-on-severity high --ignore-vuln "CVE-2023-43804:not reachable"

# How well each dependency is looked after: the OpenSSF Scorecard of its repository
pixi sbom --fetch-licenses --scorecard --report scorecard

# A standalone CycloneDX VEX beside the document, linked back to it
pixi sbom --pypi-mapping prefix --vulnerabilities osv --output sbom.cdx.json --vex vex.cdx.json

# Flag what CISA lists as actively exploited, and fail on it
pixi sbom --pypi-mapping prefix --vulnerabilities osv --kev --fail-on-kev

# Rank the rest by how likely exploitation is (FIRST EPSS), and fail at a 10% chance
pixi sbom --pypi-mapping prefix --vulnerabilities osv --epss --fail-on-epss 0.1

# Just look: an inventory (with what the manifest declared) or a license table, nothing written
pixi sbom --report packages

# Where every fact about a package came from, and which sources came back empty
pixi sbom --fetch-licenses --explain six --explain 'libz*'

# The dependency graph on the terminal, and the licenses grouped rather than listed
pixi sbom --report packages --tree --depth 2
pixi sbom --report licenses --group-by license
pixi sbom --fetch-licenses --report licenses --report-format markdown

# Make conda-installed Python packages scannable: add PyPI purls from the
# conda-forge mapping and use them as the primary identity
pixi sbom --pypi-mapping prefix --primary-purl pypi --output - | grype

# Why did it come back empty? Probe the upstreams and print the configuration
pixi sbom --doctor --fetch-licenses --vulnerabilities osv

# Somebody else's SBOM: the same reports, policy and vulnerability gate
pixi sbom --from-sbom sbom.cdx.json --vulnerabilities osv --report vulnerabilities

# ... graded first, and with the vendor's VEX applied before the gate
pixi sbom --from-sbom vendor.cdx.json --report quality
pixi sbom --from-sbom vendor.cdx.json --min-quality 70 --vulnerabilities osv --fail-on-severity high --vex-in vendor.openvex.json

# Several documents as one: an application and the vendor components it ships
pixi sbom --from-sbom app.cdx.json --from-sbom vendor.spdx.json --root-name product --output product.cdx.json

# Every pixi workspace in a monorepo, one document each under sboms/
pixi sbom --scan . --output sboms

# ... or one document for the whole tree
pixi sbom --scan . --merge --root-name product --output product.cdx.json

# Explicit lockfile and output path
pixi sbom --lockfile /path/to/pixi.lock --output /tmp/my-project.cdx.json

# A different environment / platform
pixi sbom -e prod -p linux-64

# An installed environment with no lockfile (pixi global, conda, a container)
pixi sbom --prefix ~/.pixi/envs/my-tool

# One SBOM per environment: sbom-default.cdx.json, sbom-prod.cdx.json, ...
pixi sbom --all-environments

# ... into a directory of your choice
pixi sbom --all-environments --format spdx --output reports/

# Every environment on every platform: sbom-<environment>-<platform>.cdx.json
pixi sbom --all-environments --all-platforms --output reports/

Output is reproducible: the document identifier is derived from the lockfile, and setting SOURCE_DATE_EPOCH pins the timestamp so repeated runs are byte-identical.

One document describes one environment on one platform, which is what SBOM consumers expect. Use --all-environments and --all-platforms to cover every environment and platform in the lockfile in one run.

What goes in the SBOM

The documents cover every CISA 2026 SBOM minimum element that a lockfile can support: author, timestamp, tool, generation context, and per component the name, version, supplier, purl, hashes, license and dependency relationships.

License strings are checked with the SPDX license list. Valid expressions (including deprecated identifiers still used on conda-forge) pass through unchanged; lenient spellings such as MIT/Apache-2.0 are rewritten canonically; anything else is preserved as free text.

GitHub Action

The repository is also a GitHub Action, listed on the GitHub Marketplace. It downloads the release binary, generates the documents and uploads them as an artifact; no pixi setup needed:

- uses: actions/checkout@v4
- uses: millsks/pixi-sbom@v1
  with:
    all-environments: "true"
    fetch-licenses: "true"
    deny-license: "GPL-3.0-only AGPL-3.0-only"

Add attest: "true" (with id-token: write and attestations: write) to sign the documents; verify one with gh attestation verify sbom.cdx.json --repo <owner>/<repo>. See the GitHub Action page for every input, or the Marketplace listing.

Documentation

The pages are the Markdown files in docs/, so they can be read in the repository too.

Development

pixi install            # toolchain (rust, cargo-llvm-cov, pre-commit, ...)
pixi run bootstrap      # install git hooks
pixi run test           # cargo test (unit + end-to-end)
pixi run lint           # clippy with -D warnings
pixi run cov            # coverage gate (>= 90% lines)
pixi run ci             # full gate: pre-commit, build, check, lint, cov

Cargo is never invoked directly; every command is a pixi task so the pinned toolchain is always used. End-to-end tests validate generated documents against the official JSON schemas vendored in tests/schemas/. See the development page for the full workflow, test layers, fixtures, and the release process.

License

Apache-2.0. See LICENSE.