Install & Compatibility
Where this runs
tested against v7.0.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.741s · 28.3MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 3.4s · import 0.662s · 29MB
27MB installed
● package 27MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
ControlHub
✓ from streamsets.sdk import ControlHub
Main class for interacting with StreamSets Control Hub.
DataCollector
✓ from streamsets.sdk import DataCollector
Main class for interacting with StreamSets Data Collector instances.
Topology
✓ from streamsets.sdk.sch_models import Topology
✗ from streamsets.sdk import ControlHub # for Topology methods
As of SDK v3.11.0, Topology-related methods were moved from `ControlHub` to `streamsets.sdk.sch_models.Topology` for proper scope.
This quickstart demonstrates how to connect to StreamSets Control Hub using API credentials and list available Data Collectors. It also includes an example of how to initialize a `PipelineBuilder` to create an in-memory pipeline definition. Remember that creating an object in code does not automatically deploy it to StreamSets; explicit `publish` or `add` calls are required.
import os
from streamsets.sdk import ControlHub
# Ensure CRED_ID and CRED_TOKEN are set as environment variables
# Example: export CRED_ID='your_credential_id'
# Example: export CRED_TOKEN='your_credential_token'
cred_id = os.environ.get('CRED_ID', 'YOUR_CRED_ID')
cred_token = os.environ.get('CRED_TOKEN', 'YOUR_CRED_TOKEN')
sch_url = os.environ.get('SCH_URL', 'https://cloud.streamsets.com') # Or your on-prem Control Hub URL
# Connect to Control Hub
try:
control_hub = ControlHub(sch_url=sch_url, credential_id=cred_id, credential_token=cred_token)
print(f"Successfully connected to Control Hub at {sch_url}")
# Example: List available Data Collectors
data_collectors = control_hub.get_data_collectors()
if data_collectors:
print("Available Data Collectors:")
for dc in data_collectors:
print(f" - {dc.name} (ID: {dc.id})")
else:
print("No Data Collectors found.")
# Example: Create a simple pipeline (requires a Data Collector if deployed)
# This example demonstrates creating a pipeline in memory, but not deploying it.
# For deployment, you'd typically use PipelineBuilder and then control_hub.publish_pipeline()
# or control_hub.create_job() if managing via Control Hub.
print("\nExample: Creating a simple in-memory pipeline builder (not yet deployed to Control Hub).")
pipeline_builder = control_hub.get_pipeline_builder()
dev_data_generator = pipeline_builder.add_stage('Dev Data Generator')
trash = pipeline_builder.add_stage('Trash')
dev_data_generator >> trash # Connect stages
my_pipeline = pipeline_builder.build('My First SDK Pipeline')
print(f"Created pipeline builder object: {my_pipeline.name}")
# To deploy this pipeline, you would use control_hub.publish_pipeline(my_pipeline)
except Exception as e:
print(f"Error connecting to Control Hub or performing operations: {e}")
Debug
Known issues
breakingStreamSets SDK for Python versions 4.0.0 and higher are designed for the StreamSets DataOps Platform, while versions below 4.0.0 support legacy StreamSets products. Ensure your SDK version matches the StreamSets product version you intend to interact with for compatibility.fixVerify and align your installed SDK version with your StreamSets product (Platform or Legacy). Upgrade SDK to >=4.0.0 for Platform or use <4.0.0 for Legacy products.
affects: <4.0.0
breakingStarting with SDK v3.11.0, methods related to Topologies were moved from the `streamsets.sdk.ControlHub` class to `streamsets.sdk.sch_models.Topology`. Existing code using `control_hub.get_topology_by_name()` or similar directly on the `ControlHub` object will fail.fixUpdate imports and method calls to use `from streamsets.sdk.sch_models import Topology` and interact with `Topology` objects directly for topology management.
affects: >=3.11.0
breakingThe SDK for Python v3.10.0 refactored SDC pipeline snapshots. Upgrading to 3.10.0 or later without modifying existing code to use the new snapshot syntax will result in execution failures.fixRefer to the updated documentation for `streamsets.sdk.sdc_models.Snapshot` to adjust your code to the new syntax for pipeline snapshot interactions.
affects: >=3.10.0
gotchaFor StreamSets SDK versions that interact with Control Hub (typically 4.0.0+), authentication requires API credentials (`CRED_ID` and `CRED_TOKEN`), which must be generated in Control Hub. This replaces the username and password authentication methods used in older SDK v3.x versions.fixGenerate API credentials (Credential ID and Token) in your StreamSets Control Hub instance and use them to initialize the `ControlHub` object, preferably via environment variables.
affects: >=4.0.0
gotchaWhen using the SDK, creating an object (e.g., a `PipelineBuilder` or a pipeline object) in your Python script does not automatically mean that object exists within StreamSets Control Hub or Data Collector. You must explicitly 'add' or 'publish' the object (e.g., `control_hub.publish_pipeline(pipeline)`) for it to be reflected in the StreamSets environment.
Errors
Common errors & fixes
ss-controlhub: command not found
The `ss-controlhub` CLI tool, installed with the StreamSets Python SDK, is not accessible in the system's PATH.
fixEnsure your virtual environment is activated, or add the Python site-packages 'bin' directory to your system's PATH. Reinstalling with `pip install streamsets` in a fresh environment might also resolve it.
ModuleNotFoundError: No module named 'streamsets'
The `streamsets` Python SDK package has not been installed in the current Python environment.
fixInstall the library using pip: `pip install streamsets`
Failed to authenticate to Control Hub. Status code: 401 Unauthorized
The provided API key, user credentials, or Control Hub URL is incorrect, expired, or lacks the necessary permissions.
fixVerify your `STREAMSETS_CONTROLHUB_URL`, `STREAMSETS_CONTROLHUB_USER`, and `STREAMSETS_CONTROLHUB_PASSWORD` (or API key) environment variables or direct arguments are correct and have the required access.
Pipeline with name 'My NonExistent Pipeline' not found.
The specified pipeline name or ID does not exist in Control Hub, or the user lacks permission to view it.
fixVerify the exact pipeline name or ID in Control Hub and ensure your user has appropriate permissions to access it.
requests.exceptions.ConnectionError: ('Connection refused', ...)
The Python application failed to establish a connection with the StreamSets Control Hub server, often due to an incorrect URL, network issues, or the Control Hub server being unreachable.
fixCheck if the `STREAMSETS_CONTROLHUB_URL` is correct and accessible from your environment, and ensure the Control Hub instance is running.
Upgrade
Version history
7.0.1latest on PyPI · released Apr 23, 2026
Audit
Dependencies
PythonrequiredRequired interpreter version.