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.
pip install cyclonedx-python-libVerified import paths — ran on the pinned version, not inferred.
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.
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.
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.
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.
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.
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.
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.
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.
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.