CycloneDX Python Library

11.7.0 · active · verified Mon Apr 06

The CycloneDX Python Library provides data models, validators, and serialization/deserialization capabilities for creating, rendering, and reading CycloneDX Software Bill of Materials (SBOM) documents. It is an OWASP Flagship Project and is intended as a programmatic library, not a standalone SBOM generation tool. The library maintains a frequent release cadence, often releasing new minor versions multiple times a quarter.

Warnings

breaking Deserialization behavior changed to ignore unknown properties by default. Previously, unknown properties might have caused errors during deserialization.
Fix: If strict deserialization is required, users may need to explicitly configure parsers or validate inputs against a schema prior to deserialization. Review code that relies on implicit erroring for unknown properties.
deprecated Certain exports were deprecated, and non-standard implementations were moved to a `contrib` sub-package. This includes methods like `Bom.get_component_by_purl()` which were previously available directly on the `Bom` object.
Fix: Update import paths for deprecated exports to their new locations, typically within the `cyclonedx.contrib` sub-package. Refer to the official documentation and changelog for specific refactor details. For deprecated `Bom` methods, reimplement logic or find alternative API calls.
gotcha This package is a software library for data models and manipulation, not a standalone command-line tool for generating SBOMs from projects. For CLI tools, refer to `cyclonedx-python` or `Jake`.
Fix: If seeking a CLI tool to generate SBOMs from project environments (e.g., `requirements.txt`, `Poetry` projects), use `cyclonedx-python` or `Jake`. Use `cyclonedx-python-lib` for programmatic SBOM creation, modification, or validation within your own applications.
breaking Support for Python versions older than 3.8 was dropped. Also, significant changes were made to license models and validation behavior (e.g., `Bom.validate()` can now throw `LicenseExpressionAlongWithOthersException`). The `SchemaVersion` and `OutputVersion` enums are no longer string-like.
Fix: Ensure your project uses Python 3.8 or newer. Review and update code handling license expressions and schema/output version enums. Update any custom validation logic that relied on previous behavior.
gotcha Serialization of unsupported enum values (e.g., component types, external reference types not defined in the target schema version) might result in downgrading, migration, or omission of those values in the output, potentially causing data loss.
Fix: Always validate your BOM against the target schema version before serialization to identify and address any potential data loss. Ensure all values used conform to the chosen CycloneDX schema version specification.

Install

pip install cyclonedx-python-lib Core library
pip install cyclonedx-python-lib[validation] With all validation dependencies
pip install cyclonedx-python-lib[json-validation] With JSON validation dependencies
pip install cyclonedx-python-lib[xml-validation] With XML validation dependencies

Imports

Bom
```
from cyclonedx.model.bom import Bom
```

Component

from cyclonedx.model.component import Component

Purl
```
from packageurl.contrib.url2purl import url2purl
```
The Purl class is part of `packageurl.contrib.url2purl` and not directly under `cyclonedx.model.component`.
JsonV15
```
from cyclonedx.output import JsonV15
```
Specific CycloneDX schema versions (e.g., JsonV15, XmlV14) should be imported for serialization, not a generic 'Json' or 'Xml' class.

Quickstart

This quickstart demonstrates how to programmatically create a simple CycloneDX SBOM with two components and a dependency relationship, then serialize it to JSON using Schema Version 1.5. It also includes commented-out code for deserialization as an example.

from cyclonedx.model.bom import Bom
from cyclonedx.model.component import Component
from cyclonedx.model.dependency import Dependency
from packageurl.contrib.url2purl import url2purl
from cyclonedx.output import JsonV15

# 1. Create a new BOM
bom = Bom()

# 2. Define components
component_a = Component(name='my-app', version='1.0.0')
component_a.bom_ref.value = 'pkg-a-1.0.0'

component_b_purl = url2purl('pkg:pypi/requests@2.28.1')
component_b = Component(name='requests', version='2.28.1', purl=component_b_purl)
component_b.bom_ref.value = 'pkg-b-2.28.1'

# 3. Add components to the BOM
bom.add_component(component_a)
bom.add_component(component_b)

# 4. Add a dependency relationship (optional)
dep_a_to_b = Dependency(ref=component_a.bom_ref)
dep_a_to_b.add_dependency(component_b.bom_ref)
bom.add_dependency(dep_a_to_b)

# 5. Serialize the BOM to JSON (using CycloneDX Schema Version 1.5)
outputter = JsonV15(bom)
json_output = outputter.output_as_string(indent=2)

print(json_output)

# Example of deserialization (requires `validation` extra)
# from cyclonedx.validation.schema import SchemaVersion
# from cyclonedx.parsers.json.parser import JsonParser
# parsed_bom = JsonParser(json_output).parse(SchemaVersion.V1_5)
# print(f"Parsed BOM version: {parsed_bom.get_spec_version().to_string()}")

view raw JSON →