CycloneDX Python Library

11.7.0 · active · verified Sat Apr 11

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.

Common errors

```
AttributeError: type object 'datetime.datetime' has no attribute 'fromisoformat'
```
cause This error occurs when running `cyclonedx-python-lib` on Python versions older than 3.7, as the `datetime.fromisoformat()` method was introduced in Python 3.7.

fix Upgrade your Python environment to version 3.7 or newer (the library officially supports Python >=3.9). Alternatively, for older Python 3 versions, you can use the `backports-datetime-fromisoformat` library.
```
ValueError: Unexpected key <KEY_NAME> in data being serialized to cyclonedx.model.bom.BomMetaData
```
cause This error typically arises during serialization (e.g., to JSON or XML) when the data model you've constructed contains an attribute or field that is not expected or recognized by the `cyclonedx-python-lib`'s internal data model for the specific CycloneDX schema version being used.

fix Review the CycloneDX specification for the target schema version and ensure that all fields in your Python data model (`cyclonedx.model.*` objects) correspond correctly to the specification. Remove or rename unexpected keys, or ensure they are nested correctly within the expected parent elements.
```
cyclonedx.exception.ValidationError: Validation failed: <detailed error message>
```
cause This exception is raised when attempting to validate a CycloneDX Bill of Materials (BOM) object, and the BOM does not conform to the specified CycloneDX schema version or contains invalid data according to the schema rules (e.g., incorrect data types, missing required fields, or malformed structures).

fix Examine the detailed error message provided in the `ValidationError` to identify the specific part of your BOM that is invalid. Correct the data in your `cyclonedx.model.bom.Bom` object to ensure it strictly adheres to the CycloneDX specification for your chosen schema version. For example, ensuring `metadata.authors` are lists of `OrganizationalContact` objects rather than simple strings.

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
wrong:
```
from cyclonedx.model.component import Purl
```
correct:
```
from packageurl.contrib.url2purl import url2purl
```
The Purl class is part of `packageurl.contrib.url2purl` and not directly under `cyclonedx.model.component`.
JsonV15
wrong:
```
from cyclonedx.output import Json
```
correct:
```
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 →