Registry / serialization / cyclonedx-bom

cyclonedx-bom

library7.3.0pypypiunverified

cyclonedx-bom is a Python library and command-line tool for generating CycloneDX Software Bill of Materials (SBOM) for Python projects and environments. It supports various formats and schema versions of the CycloneDX specification. The current version is 7.3.0, and it maintains an active release cadence with frequent updates, with the latest release on March 30, 2026.

serialization devops data

pip install cyclonedx-bom

github ↗package ↗docs ↗changelog ↗

INSTALL

IMPORT

SIG · CYCLONEDX-BOM

cyclonedx-bom

serializationpythonv7.3.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Demonstrates how to generate a CycloneDX SBOM for the current Python environment using the `cyclonedx-py` command-line tool and capture its JSON output.

import subprocess import json import os # Generate an SBOM for the current Python environment in JSON format # and print it to stdout. In a real scenario, you'd typically direct to a file. try: # Using `-o -` directs output to stdout result = subprocess.run( ['cyclonedx-py', 'environment', '--output-format', 'JSON', '-o', '-'], capture_output=True, text=True, check=True ) sbom_data = json.loads(result.stdout) print("Successfully generated CycloneDX SBOM (first 200 chars):") print(json.dumps(sbom_data, indent=2)[:200] + "...") except subprocess.CalledProcessError as e: print(f"Error generating SBOM: {e}") print(f"Stdout: {e.stdout}") print(f"Stderr: {e.stderr}") except json.JSONDecodeError: print("Failed to decode JSON from SBOM output.") print(f"Raw output: {result.stdout}")

cyclonedx-bom --version

Debug

Known issues

breakingIn v7.0.0, the handling of PEP 639 (improving license clarity) was finalized and is now always enabled. Consequently, the `--PEP-639` CLI switch was removed.

fix

Remove the `--PEP-639` flag from your CLI commands. PEP 639 handling is now implicit and always active.

affects: >=7.0.0

breakingIn v7.0.0, deprecated CLI switches `--schema-version` and `--outfile` were removed.

fix

Update your CLI commands to use `--spec-version` instead of `--schema-version` and `--output-file` instead of `--outfile`.

affects: >=7.0.0

gotchaThe `cyclonedx-bom` package is primarily a command-line interface (CLI) tool. Its internal Python API is not stable and explicitly not intended for public programmatic SBOM generation. For programmatic library-level interaction (e.g., creating data models, validation), you should use the `cyclonedx-python-lib` package instead.

fix

If programmatic SBOM generation is required, leverage `subprocess` to call `cyclonedx-py` commands, or consider using the `cyclonedx-python-lib` package for direct library interaction.

affects: all

gotchaDirect support for Conda as a package manager input (`--conda` or `--conda-json` CLI flags) was removed in versions prior to v4.

fix

To generate SBOMs for Conda environments, activate the environment and use `cyclonedx-py environment` or pipe `conda list --json` output to `cyclonedx-py requirements -` if applicable.

affects: <4.0

gotchaAs of v7.3.0, the new `-S` flag allows skipping `*.pth` file evaluation during environment analysis. While useful in some contexts, be aware that this may lead to incomplete component detection in your SBOM.

fix

Use the `-S` flag with caution. Evaluate whether the potential for incomplete component detection outweighs the benefits for your specific environment analysis.

affects: >=7.3.0

gotchaThis library requires Python versions 3.9 or newer, but is not compatible with Python 4.x.

fix

Ensure your environment uses Python 3.9, 3.10, 3.11, 3.12, or 3.13.

affects: all

Errors

Common errors & fixes

cyclonedx-bom: command not found

The `cyclonedx-bom` command-line tool is not found in your system's PATH, usually because it was not installed globally or the installation directory is not included in the PATH.

fix

Ensure `cyclonedx-bom` is installed and accessible: `pip install cyclonedx-bom` (for local environment) or `pipx install cyclonedx-bom` (for global execution), then verify installation with `cyclonedx-bom --version`.

Validation failed: # BOM is not valid.

The generated Software Bill of Materials (SBOM) does not conform to the CycloneDX schema, often due to malformed data (e.g., invalid URLs, incorrect license IDs, missing required fields, or wrong data types) within the components or metadata.

fix

Inspect the detailed validation errors (often printed in debug mode or alongside the main error) to identify and correct the specific issues in the input data or configuration that lead to non-compliant SBOM generation.

Some of your dependencies do not have pinned version numbers in your requirements.txt

The `cyclonedx-bom` tool detected dependencies in your `requirements.txt` file that do not have exact version pins, which prevents them from being accurately included in the generated SBOM as per CycloneDX specification requirements.

fix

Freeze your dependencies by updating your `requirements.txt` file to include exact version numbers (e.g., `package==1.2.3`) or use `pip freeze > requirements.txt` to generate a frozen list.

UnicodeDecodeError: 'charmap' codec can't decode byte X in position Y: character maps to <undefined>

This error typically occurs on Windows when `cyclonedx-bom` attempts to read a manifest file (like `requirements.txt` or `poetry.lock`) using the system's default encoding (e.g., `cp1252`) but the file is encoded in UTF-8 or another incompatible format.

fix

Ensure your manifest files are saved with UTF-8 encoding. If running on Windows, you might need to explicitly set the Python interpreter's encoding or ensure your environment uses UTF-8 by default.

Error: No such option: --format

In `cyclonedx-bom` versions 7.x and later, command-line operations use subcommands (like `export`), and options such as `--format` apply to these subcommands, not the main `cyclonedx-bom` command.

fix

Use the `export` subcommand to specify the format: `cyclonedx-bom export --format json --output bom.json`.

Upgrade

Version history

7.3.0latest on PyPI · released Mar 30, 2026

Audit

Dependencies

No dependency data recorded yet.

Agent activity

19 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/CycloneDX/cyclonedx-python ↗

packagehttps://pypi.org/project/cyclonedx-bom/ ↗

docshttps://cyclonedx-bom-tool.readthedocs.io/ ↗

changeloghttps://github.com/CycloneDX/cyclonedx-python/releases ↗