Install & Compatibility
Where this runs
tested against v1.3.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.376s · 21.3MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 2.2s · import 0.366s · 22MB
19MB installed
● package 19MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Buildkite
✓ from pybuildkite.buildkite import Buildkite
✗ from pybuildkite.buildkite import BuildKite
The class name is 'Buildkite' (lowercase 'k'). Using 'BuildKite' (uppercase 'K') will result in an ImportError or NameError.
BuildState
✓ from pybuildkite.buildkite import BuildState
Used for filtering builds by their state (e.g., RUNNING, SCHEDULED).
Initializes the Buildkite client with an API access token (preferably from an environment variable) and demonstrates how to fetch organization details and list builds for a specific pipeline. It also includes a commented-out example for creating a new build.
import os
from pybuildkite.buildkite import Buildkite, BuildState
# Get your Buildkite API access token from environment variables
api_access_token = os.environ.get('BUILDKITE_API_ACCESS_TOKEN', 'YOUR_API_ACCESS_TOKEN_HERE')
org_slug = os.environ.get('BUILDKITE_ORGANIZATION_SLUG', 'your-org-slug')
pipeline_slug = os.environ.get('BUILDKITE_PIPELINE_SLUG', 'your-pipeline-slug')
if api_access_token == 'YOUR_API_ACCESS_TOKEN_HERE':
print("Warning: Please set the BUILDKITE_API_ACCESS_TOKEN environment variable.")
print("You can generate one at: https://buildkite.com/user/api-access-tokens")
exit(1)
buildkite = Buildkite()
buildkite.set_access_token(api_access_token)
try:
# Get all info about a particular organization
org = buildkite.organizations().get_org(org_slug)
print(f"Organization Name: {org['name']}")
# List all running and scheduled builds for a particular pipeline
builds = buildkite.builds().list_all_for_pipeline(
org_slug, pipeline_slug, states=[BuildState.RUNNING, BuildState.SCHEDULED]
)
print(f"Found {len(builds)} running/scheduled builds for pipeline '{pipeline_slug}':")
for build in builds:
print(f" Build #{build['number']}: {build['state']} - {build['message']}")
# Example: Create a new build (uncomment and modify to use)
# new_build = buildkite.builds().create_build(
# org_slug, pipeline_slug, 'HEAD', 'main',
# clean_checkout=True, message="Triggered from pybuildkite quickstart!"
# )
# print(f"Created new build #{new_build['number']} in pipeline '{pipeline_slug}'.")
except Exception as e:
print(f"An error occurred: {e}")
Debug
Known issues
breakingThe underlying Buildkite REST API transitioned from v1 to v2, introducing breaking changes such as renaming 'project' properties to 'pipeline' and removing certain endpoints. While `pybuildkite` v1.x largely aligns with Buildkite API v2, users migrating from very old `pybuildkite` versions or those whose code directly relied on v1 API semantics should consult `pybuildkite`'s release notes and the official Buildkite API migration guide (https://buildkite.com/docs/api/rest#migrating-from-v1-to-v2).fixUpgrade to the latest `pybuildkite` version and review your code for usage of deprecated API endpoints or 'project' terminology. Refer to Buildkite's official API documentation for current endpoint structures.
affects: <1.0.0 (potentially)
gotchaWhen dealing with API endpoints that return large datasets, it's crucial to implement pagination. By default, `pybuildkite` might return a limited number of items per request (e.g., 100). Failing to handle pagination can lead to incomplete data retrieval.fixUse the `with_pagination=True` parameter and iterate through `next_page` results, or specify the `per_page` parameter to control the number of items returned per request. Example: `builds_response = buildkite.builds().list_all(page=1, with_pagination=True); while builds_response.next_page: ...`
affects: All versions
gotchaBuildkite API access tokens are sensitive credentials. Buildkite has updated its security policies, including new tokens being single-organization by default and deprecating retrieval of agent tokens via GraphQL for newly created tokens. Using compromised or overly permissive tokens is a significant security risk.fixAlways use API tokens with the least privilege necessary. Store tokens securely (e.g., environment variables, secret management systems) and avoid hardcoding them. Regularly rotate tokens and review their scopes on the Buildkite dashboard.
affects: All versions (user responsibility)
gotchaThe primary class for interacting with the Buildkite API is named `Buildkite` (note the lowercase 'k'). Incorrectly using `BuildKite` (uppercase 'K') due to case sensitivity will result in an `ImportError` or `NameError`.fixEnsure correct capitalization when importing: `from pybuildkite.buildkite import Buildkite`.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'pybuildkite'
The `pybuildkite` package is not installed in the Python environment, or the import statement is incorrect.
fixEnsure the library is installed using pip: `pip install pybuildkite`. If installed, verify the import statement is `from pybuildkite.buildkite import Buildkite`.
AttributeError: 'Buildkite' object has no attribute 'organizations'
This usually indicates an attempt to call a method or access an attribute on a `Buildkite` object that either does not exist, or the object has not been correctly initialized or authenticated to expose that functionality.
fixEnsure you have correctly initialized the `Buildkite` object and set your access token: `buildkite = Buildkite()` and `buildkite.set_access_token('YOUR_API_ACCESS_TOKEN')` before attempting to access API resources like `buildkite.organizations()`. buildkite.exceptions.APIException: 401 Unauthorized
The API request failed due to an invalid or missing Buildkite API access token. This means the token provided does not have the necessary permissions or is malformed.
fixVerify that `buildkite.set_access_token('YOUR_API_ACCESS_TOKEN_HERE')` is called with a valid Buildkite API access token that has the required permissions for the attempted operation. Double-check for typos or leading/trailing spaces in the token. buildkite.exceptions.APIException: 404 Not Found
The requested Buildkite resource (e.g., organization, pipeline, build) could not be found. This often happens due to incorrect slugs or IDs in the API call.
fixCheck the slugs or IDs used in your API call (e.g., organization slug, pipeline slug, build number) to ensure they are correct and correspond to existing resources in your Buildkite account.
Upgrade
Version history
1.3.0latest on PyPI · released Jul 31, 2025
Audit
Dependencies
No dependency data recorded yet.