Install & Compatibility
Where this runs
tested against v0.12.0 · 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.95 runs
installs and imports cleanly · install 0.0s · import 0.712s · 37MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 4.0s · import 0.670s · 37MB
32MB installed
● package 32MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Pipeline
✓ from buildkite_sdk import Pipeline
This quickstart demonstrates how to create a simple Buildkite pipeline programmatically using the `buildkite-sdk`. It defines two command steps and then prints the resulting pipeline in YAML format. The output can then be uploaded to Buildkite via the `buildkite-agent pipeline upload` command.
from buildkite_sdk import Pipeline
from buildkite_sdk.schema import CommandStep
# Create a new pipeline
pipeline = Pipeline()
# Add a simple command step
pipeline.add_step(CommandStep(command="echo 'Hello from Buildkite SDK!'"))
# Add another step with more detail
pipeline.add_step(
CommandStep(
label=":python: Run Python Tests",
command="pip install -r requirements.txt && pytest",
agents={
"queue": "default"
}
)
)
# Output the generated pipeline in YAML format
print(pipeline.to_yaml())
# To upload this to Buildkite, you would typically pipe the output:
# python your_script.py | buildkite-agent pipeline upload
Debug
Known issues
breakingAs the SDK generates types directly from the Buildkite pipeline schema, major schema changes in Buildkite's platform can introduce breaking changes in the SDK's generated classes and methods. Consult the changelog for specific version upgrade details.fixReview the official documentation and changelog for migration guides when upgrading, particularly for changes in pipeline step definitions or schema structures.
affects: All versions, especially major/minor releases where schema changes occur (e.g., v0.4.0 introduced breaking changes related to type generation).
gotchaThe `buildkite-sdk` is specifically designed for *generating* Buildkite pipeline YAML or JSON for dynamic pipelines, not for direct interaction with the Buildkite API (e.g., fetching build statuses, creating builds). For direct API interaction, the `pybuildkite` library (a separate project) is typically used.fixEnsure you are using the correct library for your task: `buildkite-sdk` for programmatic pipeline definition, `pybuildkite` for API client operations.
affects: All versions
gotchaThe Buildkite SDK is currently considered a 'preview' feature. While functional, this status suggests that its API or behavior might be subject to change in future releases, and users are encouraged to report any issues via GitHub.fixBe aware of the preview status and consider locking to specific minor versions to control updates. Actively monitor the GitHub repository and changelog for announcements regarding stability and API changes.
affects: All current versions (0.x.x)
gotchaThe generated pipeline YAML/JSON from the `buildkite-sdk` is not directly sent to Buildkite by the SDK itself. It must be uploaded by a `buildkite-agent` running within a Buildkite build. This is typically done by piping the script's output: `python your_script.py | buildkite-agent pipeline upload`.fixIntegrate the Python script that uses the SDK into your Buildkite pipeline definition, ensuring its output is piped to `buildkite-agent pipeline upload` within a command step.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'buildkite_sdk'
The Python package name for the `buildkite-sdk` library is `buildkite_sdk` (with an underscore), not `buildkite-sdk` (with a hyphen) as it might be installed via pip. Alternatively, the package is not installed in the environment.
fixEnsure the library is installed with `pip install buildkite-sdk` and imported correctly as `from buildkite_sdk import Pipeline`.
AttributeError: 'Pipeline' object has no attribute 'add_steps'
You are attempting to call a non-existent or misspelled method on the `Pipeline` object. The correct method to add a single step is `add_step` (singular).
fixUse the correct method name: `pipeline.add_step({'command': 'echo "Hello"'})`. buildkite-agent pipeline upload: invalid pipeline schema (Validation Failed)
The YAML or JSON output generated by the `buildkite-sdk` script does not conform to the Buildkite pipeline schema. This often happens when step definitions are missing required attributes or have incorrectly formatted values.
fixReview your Python code that defines pipeline steps and compare it against the Buildkite pipeline schema documentation to ensure all necessary fields (e.g., `command` for a command step) are present and correctly structured.
TypeError: __init__() missing 1 required positional argument: 'command'
When creating a step object (e.g., a `CommandStep`), a required argument, such as `command`, was not provided during initialization.
fixEnsure all required arguments are passed when instantiating step objects or when providing step dictionaries to methods like `pipeline.add_step()`. For a command step, this means including the 'command' key with its value.
ImportError: cannot import name 'Pipeline' from 'buildkite_sdk' (/path/to/site-packages/buildkite_sdk/__init__.py)
The `Pipeline` class is located within the `buildkite_sdk.pipeline` submodule, not directly in the top-level `buildkite_sdk` module.
fixfrom buildkite_sdk.pipeline import Pipeline
Upgrade
Version history
0.12.0latest on PyPI · released Jul 23, 2026
Audit
Dependencies
No dependency data recorded yet.