Black Duck Python API Client

1.1.3 · maintenance · verified Wed Apr 15

The `blackduck` library provides Python bindings for interacting with the Synopsys Black Duck Hub REST API. It allows users to automate tasks such as fetching project information, managing vulnerabilities, and integrating with Black Duck's security and compliance features. The current version is 1.1.3, released on April 19, 2024. While functionally stable, the project's release cadence appears to be slow, with no new PyPI versions in the past two years, suggesting a maintenance-focused status.

Warnings

breaking The `HubInstance` interface, used in older versions, will break when connecting to Black Duck instances running v2022.2 or later due to the introduction of a max page size in the REST API. It does not provide automatic paging support.
Fix: Migrate all API interactions to use the `Client` class, which correctly handles pagination.
deprecated The `HubInstance` interface is deprecated and no longer maintained. Examples using it are not guaranteed to work and any related issues will be closed as 'Won't Fix'.
Fix: Switch to using the `blackduck.Client` class for all new and existing integrations.
gotcha While some examples or older scripts might use a `.restconfig.json` file for configuration (e.g., `baseurl`, `api_token`), it is generally recommended to use environment variables (`BLACKDUCK_URL`, `BLACKDUCK_TOKEN`) for consistency and security in automated environments, especially for the `Client` class.
Fix: Configure Black Duck URL and API token via environment variables `BLACKDUCK_URL` and `BLACKDUCK_TOKEN` respectively, and ensure the `Client` is initialized using these values.
gotcha Despite version 1.1.3 being released on April 19, 2024, the PyPI package has not seen further updates in the last two years (as of April 15, 2026). Snyk reports the maintenance status as 'Inactive', suggesting a potentially low attention from maintainers for new releases, although the GitHub repository shows some recent activity and an upcoming v1.1.4.
Fix: Monitor the GitHub repository for activity and upcoming releases (v1.1.4 has been mentioned). Exercise caution regarding the responsiveness to new issues or feature requests if the release cadence remains slow.
gotcha When integrating with Black Duck Detect (a separate scanning tool, often used in conjunction with this library), ensure that Python environments (e.g., virtualenvs) and package managers (pip, pipenv, poetry) are correctly configured and accessible by Detect. Incorrect setup can lead to incomplete or no results for Python project scans.
Fix: Consult Black Duck Detect's Python support documentation. Ensure Python, pip executables, and `requirements.txt`/`pyproject.toml` files are correctly identified and that Detect is run within the appropriate virtual environment if applicable.

Install

pip install blackduck Install stable version
pip install blackduck[mcp] Install with Model Context Protocol (MCP) support

Imports

Client
wrong:
```
from blackduck.HubRestApi import HubInstance
```
correct:
```
from blackduck import Client
```
The `HubInstance` class is deprecated and does not support pagination introduced in Black Duck v2022.2. The `Client` class is the recommended and actively maintained interface.

Quickstart

This quickstart demonstrates how to initialize the `Client` and fetch a list of projects. It expects `BLACKDUCK_URL` and `BLACKDUCK_TOKEN` to be set as environment variables for secure authentication. The `Client` automatically handles API pagination.

import os
from blackduck import Client
import logging

logging.basicConfig(
    level=logging.INFO,
    format="[%(asctime)s] {%(module)s:%(lineno)d} %(levelname)s - %(message)s"
)

# Ensure BLACKDUCK_URL and BLACKDUCK_TOKEN environment variables are set
bd_url = os.environ.get('BLACKDUCK_URL', '')
bd_token = os.environ.get('BLACKDUCK_TOKEN', '')

if not bd_url or not bd_token:
    print("Error: BLACKDUCK_URL and BLACKDUCK_TOKEN environment variables must be set.")
    # In a real application, you might raise an exception or exit
    exit(1)

try:
    # Initialize the Black Duck Client
    bd = Client(
        token=bd_token,
        base_url=bd_url,
        # verify=False # Uncomment to disable TLS certificate verification (use with caution)
    )

    print(f"Successfully connected to Black Duck at {bd_url}")
    print("Listing first 5 projects:")

    # Fetch and print project names (Client handles pagination automatically)
    projects = bd.get_resource(name='projects', limit=5)
    for project in projects:
        print(f"- {project.get('name')}")

except Exception as e:
    print(f"An error occurred: {e}")

view raw JSON →