Beaker Python Client

2.6.0 · active · verified Thu Apr 16

beaker-py is a lightweight, standalone, pure Python client for the Beaker platform, which is a machine learning experiment and dataset management system. It provides an RPC-based client to interact with Beaker servers. The library is actively maintained, with its latest version being 2.6.0, and follows a continuous release cadence.

Common errors

```
Failed to interact with Beaker: BeakerPermissionsError: User does not have permission...
```
cause The authenticated user lacks the necessary permissions for the requested operation or resource.

fix Check the permissions for your Beaker user token or the configured user within the Beaker platform. Ensure the default workspace specified has the correct access rights for your user.
```
Failed to interact with Beaker: BeakerConfigurationError: No Beaker configuration file found at ... or BEAKER_TOKEN environment variable set.
```
cause The Beaker client could not find valid authentication credentials.

fix Set the `BEAKER_TOKEN` environment variable, e.g., `export BEAKER_TOKEN="your_token"`, or ensure a valid `~/.beaker/config.yml` file exists with your Beaker configuration.
```
Failed to interact with Beaker: BeakerWorkspaceNotFound: Workspace 'your_org/non_existent_workspace' not found.
```
cause The specified Beaker workspace either does not exist or the authenticated user does not have access to it.

fix Verify the exact name or ID of the workspace in the Beaker UI or CLI. Ensure your `BEAKER_TOKEN` grants access to this specific workspace.

Warnings

breaking Version 2.x introduces significant breaking changes from version 1.x. The project codebase and documentation location also moved. Old imports and API calls from `beaker-py<2.0` will not work with `beaker-py>=2.0`.
Fix: Consult the official v1 -> v2 migration guide (beaker-py-docs.allen.ai) for detailed steps. Ensure your `pip install` command is specific if you need version 1, e.g., `pip install 'beaker-py<2.0'`.
gotcha Authentication and configuration are critical. The client relies on a `BEAKER_TOKEN` environment variable or a configuration file at `~/.beaker/config.yml`. Without proper credentials, most operations will fail with authentication or permission errors.
Fix: Set the `BEAKER_TOKEN` environment variable to your Beaker user token or configure `~/.beaker/config.yml` as per Beaker CLI instructions. Use `Beaker.from_env()` for automatic configuration loading.
gotcha Do not confuse `beaker-py` (client for AllenAI's Beaker platform) with the `beaker` library (a session and caching library). They are distinct projects with different purposes and APIs.
Fix: Always use `pip install beaker-py` and `from beaker import Beaker` when targeting the Beaker platform client. Verify the GitHub repository (allenai/beaker) if in doubt.

Install

pip install beaker-py Install latest version
pip install 'beaker-py<2.0' Install v1.x (legacy)

Imports

Beaker
```
from beaker import Beaker
```

Quickstart

The quickstart demonstrates initializing the Beaker client using `Beaker.from_env()`, which automatically picks up configuration from `~/.beaker/config.yml` or the `BEAKER_TOKEN` environment variable. It then attempts to list datasets within a specified workspace.

import os
from beaker import Beaker

# Ensure BEAKER_TOKEN environment variable is set or a ~/.beaker/config.yml exists
# Example: export BEAKER_TOKEN="your_beaker_user_token"

# Or, for a quick demonstration without a real token (will likely fail auth):
# os.environ['BEAKER_TOKEN'] = os.environ.get('BEAKER_TOKEN', 'dummy-token-for-example')

try:
    # Instantiate the Beaker client, optionally specifying a default workspace
    with Beaker.from_env(default_workspace="your_org/your_workspace") as beaker:
        # Example: List datasets (requires proper auth and workspace)
        print(f"Beaker client initialized for workspace: {beaker.workspace.current.name}")
        datasets = beaker.dataset.list()
        if datasets:
            print(f"Found {len(datasets)} datasets, e.g., {datasets[0].name}")
        else:
            print("No datasets found or unable to list.")
except Exception as e:
    print(f"Failed to interact with Beaker: {e}")
    print("Please ensure BEAKER_TOKEN is set or ~/.beaker/config.yml is configured correctly.")

view raw JSON →