beaker-py 2.5.8


pip install beaker-py

  Latest version

Released: Apr 03, 2026
Navigation
Meta
Author: Allen Institute for Artificial Intelligence, Pete Walsh
Requires Python: >=3.10
Classifiers

Intended Audience
  • Science/Research

Programming Language
  • Python :: 3

Topic
  • Scientific/Engineering :: Artificial Intelligence

Beaker-py

A lightweight pure-Python client for Beaker.

Quick Links

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,
        preemptible=True,
    )

    # 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, you can run checks and tests locally with:

make checks

Releases

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

  1. 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#
  1. 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.
  2. Ensure the CHANGELOG.md has a section at the top for the new release (## vX.X.X - %Y-%m-%d).
  3. Run make publish for a stable release or make publish-nightly for a nightly pre-release.
2.5.8 Apr 03, 2026
2.5.7 Apr 03, 2026
2.5.7.dev20260402 Apr 02, 2026
2.5.6 Mar 26, 2026
2.5.5 Mar 09, 2026
2.5.4 Jan 14, 2026
2.5.3 Nov 25, 2025
2.5.2 Nov 21, 2025
2.5.1 Oct 14, 2025
2.5.0 Aug 20, 2025
2.4.7 Jul 21, 2025
2.4.6 Jul 12, 2025
2.4.5 Jul 10, 2025
2.4.4 Jun 16, 2025
2.4.3 Jun 04, 2025
2.4.2 May 28, 2025
2.4.1 May 20, 2025
2.4.0 May 19, 2025
2.3.0 May 15, 2025
2.2.1 May 13, 2025
2.2.0 May 13, 2025
2.1.1 May 12, 2025
2.1.0 May 09, 2025
2.0.4 May 06, 2025
2.0.3 May 02, 2025
2.0.2 May 01, 2025
2.0.1 May 01, 2025
2.0.1.dev20250430 Apr 30, 2025
2.0.1.dev20250429 Apr 29, 2025
2.0.1.dev20250428 Apr 28, 2025
2.0.1.dev20250426 Apr 26, 2025
2.0.1.dev20250425 Apr 26, 2025
2.0.0 Apr 26, 2025
2.0.0.dev20250425 Apr 26, 2025
2.0.0.dev0 Apr 26, 2025
1.38.1 Oct 14, 2025
1.38.0 Oct 10, 2025
1.37.0 Sep 15, 2025
1.36.4 Jul 16, 2025
1.36.3 Jul 11, 2025
1.36.2 Apr 24, 2025
1.36.1 Apr 23, 2025
1.36.0 Apr 23, 2025
1.35.0 Apr 22, 2025
1.34.3 Apr 15, 2025
1.34.2 Apr 14, 2025
1.34.1 Feb 26, 2025
1.34.0 Feb 25, 2025
1.33.0 Feb 25, 2025
1.32.3 Dec 11, 2024
1.32.2 Nov 14, 2024
1.32.1 Nov 01, 2024
1.32.0 Oct 07, 2024
1.31.3 Aug 30, 2024
1.31.2 Jul 26, 2024
1.31.1 Jul 14, 2024
1.31.0 Jul 08, 2024
1.30.0 Jun 14, 2024
1.29.1 Jun 13, 2024
1.29.0 Jun 13, 2024
1.28.0 Jun 13, 2024
1.27.2 May 31, 2024
1.27.1 May 31, 2024
1.27.0 May 31, 2024
1.26.15 May 30, 2024
1.26.14 May 29, 2024
1.26.13 May 28, 2024
1.26.12 May 10, 2024
1.26.11 May 10, 2024
1.26.10 May 02, 2024
1.26.9 May 02, 2024
1.26.8 May 01, 2024
1.26.7 Apr 30, 2024
1.26.6 Apr 24, 2024
1.26.5 Apr 18, 2024
1.26.4 Apr 10, 2024
1.26.3 Mar 20, 2024
1.26.2 Mar 01, 2024
1.26.1 Feb 29, 2024
1.26.0 Feb 28, 2024
1.25.1 Feb 26, 2024
1.25.0 Feb 22, 2024
1.24.0 Jan 30, 2024
1.23.0 Dec 15, 2023
1.22.0 Sep 25, 2023
1.21.0 Sep 08, 2023
1.20.1 Sep 01, 2023
1.20.0 Jul 28, 2023
1.19.0 Jul 17, 2023
1.18.8 Jul 12, 2023
1.18.7 Jun 19, 2023
1.18.6 Jun 02, 2023
1.18.5 May 25, 2023
1.18.4 Apr 27, 2023
1.18.3 Apr 19, 2023
1.18.2 Mar 22, 2023
1.18.1 Mar 14, 2023
1.18.0 Mar 08, 2023
1.17.7 Feb 20, 2023
1.17.6 Feb 20, 2023
1.17.5 Feb 18, 2023
1.17.4 Feb 17, 2023
1.17.3 Feb 17, 2023
1.17.2 Feb 15, 2023
1.17.1 Feb 14, 2023
1.17.0 Feb 13, 2023
1.16.0 Jan 26, 2023
1.15.0 Jan 19, 2023
1.14.1 Jan 18, 2023
1.14.0 Jan 17, 2023
1.13.2 Jan 04, 2023
1.13.1 Dec 21, 2022
1.13.0 Dec 09, 2022
1.12.1 Dec 08, 2022
1.12.0 Nov 23, 2022
1.11.6 Nov 22, 2022
1.11.5 Nov 16, 2022
1.11.4 Nov 07, 2022
1.11.3 Oct 28, 2022
1.11.2 Oct 07, 2022
1.11.1 Oct 07, 2022
1.11.0 Oct 06, 2022
1.10.3 Sep 28, 2022
1.10.2 Sep 27, 2022
1.10.1 Sep 23, 2022
1.10.0 Sep 21, 2022
1.9.2 Sep 21, 2022
1.9.1 Sep 15, 2022
1.9.0 Sep 14, 2022
1.8.1 Sep 09, 2022
1.8.0 Sep 09, 2022
1.7.4 Sep 07, 2022
1.7.3 Sep 06, 2022
1.7.2 Sep 06, 2022
1.7.1 Aug 31, 2022
1.7.0 Aug 30, 2022
1.6.9 Aug 01, 2022
1.6.8 Jul 27, 2022
1.6.7 Jul 20, 2022
1.6.6 Jul 19, 2022
1.6.5 Jul 15, 2022
1.6.4 Jul 14, 2022
1.6.3 Jul 05, 2022
1.6.2 Jun 27, 2022
1.6.1 Jun 24, 2022
1.6.0 Jun 17, 2022
1.5.1 Jun 16, 2022
1.5.0 Jun 16, 2022
1.4.2 Jun 13, 2022
1.4.1 Jun 10, 2022
1.4.0 Jun 09, 2022
1.3.0 May 31, 2022
1.2.0 May 25, 2022
1.1.0 May 18, 2022
1.0.0 May 13, 2022
0.15.3 May 10, 2022
0.15.2 May 10, 2022
0.15.1 May 06, 2022
0.15.0 May 06, 2022
0.14.1 May 05, 2022
0.14.0 May 04, 2022
0.13.2 Apr 29, 2022
0.13.1 Apr 28, 2022
0.13.0 Apr 27, 2022
0.12.0 Apr 26, 2022
0.11.0 Apr 21, 2022
0.10.0 Apr 21, 2022
0.9.0 Apr 19, 2022
0.8.4 Apr 18, 2022
0.8.3 Apr 14, 2022
0.8.2 Apr 14, 2022
0.8.1 Apr 13, 2022
0.8.0 Apr 12, 2022
0.7.0 Apr 12, 2022
0.6.1 Apr 11, 2022
0.6.0 Apr 11, 2022
0.5.5 Apr 11, 2022
0.5.4 Apr 10, 2022
0.5.3 Apr 08, 2022
0.5.2 Apr 07, 2022
0.5.1 Apr 07, 2022
0.5.0 Apr 07, 2022
0.4.3 Apr 06, 2022
0.4.2 Apr 04, 2022
0.4.1 Apr 04, 2022
0.4.0 Apr 03, 2022
0.3.9 Apr 02, 2022
0.3.8 Apr 02, 2022
0.2.8 Mar 31, 2022
0.2.7 Mar 31, 2022
0.2.6 Jan 20, 2022
0.2.5 Dec 14, 2021
0.2.4 Dec 09, 2021
0.2.3 Dec 09, 2021
0.2.2 Dec 08, 2021
0.2.1 Dec 08, 2021
0.2.0 Dec 07, 2021
0.1.0 Nov 19, 2021

Wheel compatibility matrix

Platform Python 3
any

Files in release

Extras:
Dependencies:
requests
packaging
PyYAML
grpcio (>=1.70.0)
protobuf (<7.0,>=5.0)
google-crc32c