Python

Publish a package

The following curl command (which you'll need to modify as required before submitting) describes the process above to publish a Python package to your Python source registry:

curl -X POST https://api.buildkite.com/v2/packages/organizations/{org.slug}/registries/{registry.slug}/packages \
  -H "Authorization: Bearer $REGISTRY_WRITE_TOKEN" \
  -F "file=@<path_to_file>"

where:

• {org.slug} can be obtained from the end of your Buildkite URL, after accessing Package Registries or Pipelines in the global navigation of your organization in Buildkite.

• {registry.slug} is the slug of your Python source registry, which is the kebab-case version of this registry's name, and can be obtained after accessing Package Registries in the global navigation > your Python source registry from the Registries page.

• $REGISTRY_WRITE_TOKEN is your API access token used to publish/upload packages to your Python source registry. Ensure this access token has the Read Packages and Write Packages REST API scopes, which allows this token to publish packages to any source registry your user account has access to within your Buildkite organization.

• <path_to_file> is the full path required to the package file. If the file is located in the same directory that this command is running from, then no path is required.

For example, to upload the file my-python-package-0.9.7b1.tar.gz from the current directory to the My Python packages source registry in the My organization Buildkite organization, run the curl command:

curl -X POST https://api.buildkite.com/v2/packages/organizations/my-organization/registries/my-python-packages/packages \
  -H "Authorization: Bearer $REPLACE_WITH_YOUR_REGISTRY_WRITE_TOKEN" \
  -F "file=@my-python-package-0.9.7b1.tar.gz"

Access a package's details

A Python package's details can be accessed from this registry through the Releases (tab) section of your Python source registry page. To do this:

1. Select Package Registries in the global navigation to access the Registries page.
2. Select your Python source registry on this page.
3. On your Python source registry page, select the package to display its details.

The package's details page provides the following information in the following sections:

• Installation (tab): the installation instructions.
• Contents (tab, where available): a list of directories and files contained within the package.
• Details (tab): a list of checksum values for this package—MD5, SHA1, SHA256, and SHA512.
• About this version: a brief (metadata) description about the package.

• Details: details about:

  • the name of the package (typically the file name excluding any version details and extension).
  • the package version.
  • the source registry the package is located in.
  • the package's visibility (based on its registry's visibility)—whether the package is Private and requires authentication to access, or is publicly accessible.
  • the distribution name / version.
  • additional optional metadata contained within the package, such as a homepage, licenses, etc.

• Pushed: the date when the last package was uploaded to the source registry.

• Total files: the total number of files (and directories) within the package.

• Dependencies: the number of dependency packages required by this package.

• Package size: the storage size (in bytes) of this package.

• Downloads: the number of times this package has been downloaded.

Downloading a package

A Python package can be downloaded from the package's details page. To do this:

1. Access the package's details.
2. Select Download.

Installing a package from a source registry

A Python package can be installed using code snippet details provided on the package's details page. To do this:

1. Access the package's details.
2. Ensure the Installation > Instructions section is displayed.
3. Copy the relevant code snippet from the Registry Configuration section and paste it into either the package installer for Python (pip) configuration (pip.conf) file or end of the virtualenv requirements.txt file.
4. Run the installation command from the Package Installation section.

Registry Configuration

The pip.conf code snippet is based on this format:

# Add this to the [global] section in your ~/.pip/pip.conf:
[global]
extra-index-url="https://buildkite:{registry.read.token}@packages.buildkite.com/{org.slug}/{registry.slug}/pypi/simple"

where:

• {registry.read.token} is your API access token or registry token used to download packages from your Python source registry. Ensure this access token has the Read Packages REST API scope, which allows this token to download packages from any registry your user account has access to within your Buildkite organization. This URL component, along with its surrounding buildkite: and @ components are not required for registries that are publicly accessible.

• {org.slug} can be obtained from the end of your Buildkite URL, after accessing Package Registries or Pipelines in the global navigation of your organization in Buildkite.

• {registry.slug} is the slug of your registry, which is the kebab-case version of your registry name, and can be obtained after accessing Package Registries in the global navigation > your registry from the Registries page.

The alternative requirements.txt (for virtualenv) code snippet is based on this format:

# Otherwise if installing on a virtualenv, add this to the bottom of your requirements.txt:
--extra-index-url="https://buildkite:{registry.read.token}@packages.buildkite.com/{org.slug}/{registry.slug}/pypi/simple"

Package Installation

Use pip to install the package:

pip install package-name==version-number

where:

• package-name is the name of your package.

• version-number is the version number of this package.

Installing a package from a composite registry

If your Python source registry is an upstream of a composite registry, you can install one of its packages using the code snippet details provided on the composite registry's Setup & Usage page. To do this:

1. Select Package Registries in the global navigation to access the Registries page.
2. Select your Python composite registry on this page.
3. Select the Setup & Usage tab to reveal the Usage Instructions page.
4. Select either the pip or uv tab, based on your Python package management tool.
5. Run the relevant installation command from either of the first two code snippets. Learn more about this in Package installation from a composite registry, below.

6. Copy the relevant code snippet/s from the third (or later) code snippets and for:

   • The package installer for Python (pip), paste this code snippet into either the pip.conf configuration file or the end of the virtualenv requirements.txt file.
   • The uv Python package management tool, paste this code snippet into the pyproject.toml configuration file.

   Learn more about this in Composite registry configuration, below.

Package installation from a composite registry

For pip, use one of these pip commands (with either the --index-url or --extra-index-url options) to install the package:

pip install --index-url=https://buildkite:{registry.read.token}@packages.buildkite.com/{org.slug}/{registry.slug}/pypi/simple ...

or

pip install --extra-index-url=https://buildkite:{registry.read.token}@packages.buildkite.com/{org.slug}/{registry.slug}/pypi/simple ...

where:

• {registry.read.token} is your API access token or registry token used to download packages from your Python composite registry. Ensure this access token has the Read Packages REST API scope, which allows this token to download packages from any registry your user account has access to within your Buildkite organization.

• {org.slug} can be obtained from the end of your Buildkite URL, after accessing Package Registries or Pipelines in the global navigation of your organization in Buildkite.

• {registry.slug} is the slug of your registry, which is the kebab-case version of your registry name, and can be obtained after accessing Package Registries in the global navigation > your registry from the Registries page.

Likewise, for uv, use one of these uv commands (with either the --index-url or --extra-index-url options) to install the package:

uv sync --index-url=https://buildkite:{registry.read.token}@packages.buildkite.com/{org.slug}/{registry.slug}/pypi/simple

or

uv sync --extra-index-url=https://buildkite:{registry.read.token}@packages.buildkite.com/{org.slug}/{registry.slug}/pypi/simple

Composite registry configuration

For pip, modify the following code snippet and add it to the pip.conf file:

[global]
index-url = https://buildkite:{registry.read.token}@packages.buildkite.com/{org.slug}/{registry.slug}/pypi/simple

where:

• {registry.read.token} is your API access token or registry token used to download packages from your Python composite registry. Ensure this access token has the Read Packages REST API scope, which allows this token to download packages from any registry your user account has access to within your Buildkite organization.

• {org.slug} can be obtained from the end of your Buildkite URL, after accessing Package Registries or Pipelines in the global navigation of your organization in Buildkite.

• {registry.slug} is the slug of your registry, which is the kebab-case version of your registry name, and can be obtained after accessing Package Registries in the global navigation > your registry from the Registries page.

As an alternative virtualenv for pip, modify the following code snippet and add it to the requirements.txt file:

--index-url="https://buildkite:{registry.read.token}@packages.buildkite.com/{org.slug}/{registry.slug}/pypi/simple"

For uv, modify the following code snippet and add it to the pyproject.toml file:

[tool.uv]
index-url = "https://buildkite:{registry.read.token}@packages.buildkite.com/{org.slug}/{registry.slug}/pypi/simple"