Beaker-py

A lightweight pure-Python client for Beaker.

Quick Links

📝 Docs and examples:
🌍 Ecosystem:
- beaker-gantry
- beaker-run-action

Installing

Installing with `pip`

beaker-py is available on PyPI. Just run

pip install beaker-py

Installing from source

To install beaker-py from source, first clone the repository:

git clone https://github.com/allenai/beaker.git

Then create or activate a Python virtual environment, and run:

cd beaker/bindings/python
make dev-install

Quick start

If you've already configured the Beaker command-line client, beaker-py will find and use the existing configuration file (usually located at $HOME/.beaker/config.yml) or BEAKER_TOKEN environment variable.

Then you can instantiate the Beaker client with the .from_env() class method:

from beaker import Beaker

with Beaker.from_env() as beaker:
    ...

With the Python client, you can:

Query Clusters with beaker.cluster.* methods. For example:
```
beaker.cluster.get("ai2/jupiter-cirrascale-2")
```
Manage Datasets with beaker.dataset.* methods. For example:
```
beaker.dataset.create(dataset_name, source_dir)
```
Manage Experiments with beaker.experiment.* and beaker.workload.* methods. For example:
```
beaker.experiment.create(spec=spec, name=name)
```
Manage Groups with beaker.group.* methods. For example:
```
beaker.group.create(name)
```
Manage Images with beaker.image.* methods. For example:
```
beaker.image.update(image, name=name)
```
Manage Secrets with beaker.secret.* methods. For example:
```
beaker.secret.write(name, value)
```
Manage Workspaces with beaker.workspace.* methods. For example:
```
beaker.workspace.create("ai2/new_workspace")
```
Track Jobs with beaker.job.* methods. For example:
```
beaker.job.logs(job, follow=True)
```
Create and process Queues with beaker.queue.* methods. For example:
```
beaker.queue.create("my-work-queue", batch_size=4)
```

If you're coming from v1 of beaker-py, consider reading the migration guide.

Example workflow

Launch and follow an experiment like beaker-gantry does:

import time
from beaker import Beaker, BeakerExperimentSpec, BeakerJobPriority


with Beaker.from_env() as beaker:
    # Build experiment spec...
    spec = BeakerExperimentSpec.new(
        description="beaker-py test run",
        beaker_image="petew/hello-world",
        priority=BeakerJobPriority.low,
        min_runtime="1h",
    )

    # Create experiment workload...
    workload = beaker.experiment.create(spec=spec)

    # Wait for job to be created...
    while (job := beaker.workload.get_latest_job(workload)) is None:
        print("waiting for job to start...")
        time.sleep(1.0)

    # Follow logs...
    print("Job logs:")
    for job_log in beaker.job.logs(job, follow=True):
        print(job_log.message.decode())

See the integration tests for more examples.

Development

After installing from source, set BEAKER_TOKEN in your environment.

Then, you can run checks and tests locally with:

make checks

Releases

At the moment releases need to be published manually by following these steps:

Ensure you've authenticated with PyPI through a ~/.pypirc file and have write permissions to the beaker-py project. The local ~/.pypirc file looks like:

[distutils]
index-servers = pypi

[pypi]
username = __token__
password = #beaker-py pypi API token from 1pass#

Ensure the target release version defined in src/beaker/version.py is correct, or change the version on the fly by adding the Make argument BEAKER_PY_VERSION=X.X.X to the command in the next step.
Ensure the CHANGELOG.md has a section at the top for the new release (## vX.X.X - %Y-%m-%d).
Run make publish for a stable release or make publish-nightly for a nightly pre-release.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

beaker_py-2.7.2.tar.gz (112.9 kB view details)

Uploaded Aug 11, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

beaker_py-2.7.2-py3-none-any.whl (124.0 kB view details)

Uploaded Aug 11, 2026 Python 3

File details

Details for the file beaker_py-2.7.2.tar.gz.

File metadata

Download URL: beaker_py-2.7.2.tar.gz
Upload date: Aug 11, 2026
Size: 112.9 kB
Tags: Source
Uploaded using Trusted Publishing? No
Uploaded via: twine/6.1.0 CPython/3.12.9

File hashes

Hashes for beaker_py-2.7.2.tar.gz
Algorithm	Hash digest
SHA256	`52170b97ad4f35d9fbea913786a7becd929eca63dda186156c6533d88225706b`
MD5	`372406895a886febe211507e86fc22fa`
BLAKE2b-256	`469ab3458811250ca8a0cb012d86a8c1e8aacb489ede22216d43c15f53b7b1dc`

See more details on using hashes here.

File details

Details for the file beaker_py-2.7.2-py3-none-any.whl.

File metadata

Download URL: beaker_py-2.7.2-py3-none-any.whl
Upload date: Aug 11, 2026
Size: 124.0 kB
Tags: Python 3
Uploaded using Trusted Publishing? No
Uploaded via: twine/6.1.0 CPython/3.12.9

File hashes

Hashes for beaker_py-2.7.2-py3-none-any.whl
Algorithm	Hash digest
SHA256	`5c07799f208c68cf7c880d670fbfa69c794eca1c34f01b9c7f61289cce592c1b`
MD5	`d9a0ffb87a0ffb16c5e22a66c5f99a49`
BLAKE2b-256	`0431b2c7077837404c694c47ee955ff6436917b0693e9741339e057d8e83dd48`