{"id":8877,"library":"beaker-py","title":"Beaker Python Client","description":"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.","status":"active","version":"2.6.0","language":"en","source_language":"en","source_url":"https://github.com/allenai/beaker","tags":["machine learning","mlops","experiment management","cloud","allenai"],"install":[{"cmd":"pip install beaker-py","lang":"bash","label":"Install latest version"},{"cmd":"pip install 'beaker-py<2.0'","lang":"bash","label":"Install v1.x (legacy)"}],"dependencies":[],"imports":[{"symbol":"Beaker","correct":"from beaker import Beaker"}],"quickstart":{"code":"import os\nfrom beaker import Beaker\n\n# Ensure BEAKER_TOKEN environment variable is set or a ~/.beaker/config.yml exists\n# Example: export BEAKER_TOKEN=\"your_beaker_user_token\"\n\n# Or, for a quick demonstration without a real token (will likely fail auth):\n# os.environ['BEAKER_TOKEN'] = os.environ.get('BEAKER_TOKEN', 'dummy-token-for-example')\n\ntry:\n    # Instantiate the Beaker client, optionally specifying a default workspace\n    with Beaker.from_env(default_workspace=\"your_org/your_workspace\") as beaker:\n        # Example: List datasets (requires proper auth and workspace)\n        print(f\"Beaker client initialized for workspace: {beaker.workspace.current.name}\")\n        datasets = beaker.dataset.list()\n        if datasets:\n            print(f\"Found {len(datasets)} datasets, e.g., {datasets[0].name}\")\n        else:\n            print(\"No datasets found or unable to list.\")\nexcept Exception as e:\n    print(f\"Failed to interact with Beaker: {e}\")\n    print(\"Please ensure BEAKER_TOKEN is set or ~/.beaker/config.yml is configured correctly.\")","lang":"python","description":"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."},"warnings":[{"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'`.","message":"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`.","severity":"breaking","affected_versions":">=2.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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.","cause":"The authenticated user lacks the necessary permissions for the requested operation or resource.","error":"Failed to interact with Beaker: BeakerPermissionsError: User does not have permission..."},{"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.","cause":"The Beaker client could not find valid authentication credentials.","error":"Failed to interact with Beaker: BeakerConfigurationError: No Beaker configuration file found at ... or BEAKER_TOKEN environment variable set."},{"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.","cause":"The specified Beaker workspace either does not exist or the authenticated user does not have access to it.","error":"Failed to interact with Beaker: BeakerWorkspaceNotFound: Workspace 'your_org/non_existent_workspace' not found."}]}