{"library":"cyclonedx-python-lib","title":"CycloneDX Python Library","description":"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.","status":"active","version":"11.7.0","language":"en","source_language":"en","source_url":"https://github.com/CycloneDX/cyclonedx-python-lib","tags":["security","sbom","cyclonedx","supply chain","bill-of-materials"],"install":[{"cmd":"pip install cyclonedx-python-lib","lang":"bash","label":"Core library"},{"cmd":"pip install cyclonedx-python-lib[validation]","lang":"bash","label":"With all validation dependencies"},{"cmd":"pip install cyclonedx-python-lib[json-validation]","lang":"bash","label":"With JSON validation dependencies"},{"cmd":"pip install cyclonedx-python-lib[xml-validation]","lang":"bash","label":"With XML validation dependencies"}],"dependencies":[{"reason":"Required Python version range.","package":"python","version":">=3.9,<4.0","optional":false},{"reason":"Runtime dependency for older Python versions.","package":"typing_extensions","version":">=4.6; python_version<\"3.13\"","optional":false},{"reason":"Runtime dependency for schema validation.","package":"referencing","version":">=0.28.4","optional":false}],"imports":[{"symbol":"Bom","correct":"from cyclonedx.model.bom import Bom"},{"symbol":"Component","correct":"from cyclonedx.model.component import Component"},{"note":"The Purl class is part of `packageurl.contrib.url2purl` and not directly under `cyclonedx.model.component`.","wrong":"from cyclonedx.model.component import Purl","symbol":"Purl","correct":"from packageurl.contrib.url2purl import url2purl"},{"note":"Specific CycloneDX schema versions (e.g., JsonV15, XmlV14) should be imported for serialization, not a generic 'Json' or 'Xml' class.","wrong":"from cyclonedx.output import Json","symbol":"JsonV15","correct":"from cyclonedx.output import JsonV15"}],"quickstart":{"code":"from cyclonedx.model.bom import Bom\nfrom cyclonedx.model.component import Component\nfrom cyclonedx.model.dependency import Dependency\nfrom packageurl.contrib.url2purl import url2purl\nfrom cyclonedx.output import JsonV15\n\n# 1. Create a new BOM\nbom = Bom()\n\n# 2. Define components\ncomponent_a = Component(name='my-app', version='1.0.0')\ncomponent_a.bom_ref.value = 'pkg-a-1.0.0'\n\ncomponent_b_purl = url2purl('pkg:pypi/requests@2.28.1')\ncomponent_b = Component(name='requests', version='2.28.1', purl=component_b_purl)\ncomponent_b.bom_ref.value = 'pkg-b-2.28.1'\n\n# 3. Add components to the BOM\nbom.add_component(component_a)\nbom.add_component(component_b)\n\n# 4. Add a dependency relationship (optional)\ndep_a_to_b = Dependency(ref=component_a.bom_ref)\ndep_a_to_b.add_dependency(component_b.bom_ref)\nbom.add_dependency(dep_a_to_b)\n\n# 5. Serialize the BOM to JSON (using CycloneDX Schema Version 1.5)\noutputter = JsonV15(bom)\njson_output = outputter.output_as_string(indent=2)\n\nprint(json_output)\n\n# Example of deserialization (requires `validation` extra)\n# from cyclonedx.validation.schema import SchemaVersion\n# from cyclonedx.parsers.json.parser import JsonParser\n# parsed_bom = JsonParser(json_output).parse(SchemaVersion.V1_5)\n# print(f\"Parsed BOM version: {parsed_bom.get_spec_version().to_string()}\")","lang":"python","description":"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."},"warnings":[{"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.","message":"Deserialization behavior changed to ignore unknown properties by default. Previously, unknown properties might have caused errors during deserialization.","severity":"breaking","affected_versions":">=11.0.0"},{"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.","message":"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.","severity":"deprecated","affected_versions":">=11.6.0"},{"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.","message":"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`.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"breaking","affected_versions":">=5.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-06T00:00:00.000Z","next_check":"2026-07-05T00:00:00.000Z"}