Install & Compatibility
Where this runs
tested against v0.35.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.915 runs
installs and imports cleanly · install 0.0s · import 6.195s · 37MB
glibcpy 3.10–3.915 runs
installs and imports cleanly · install 12.9s · import 5.705s · 37MB
35MB installed
● package 35MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Eval
✓ from braintrust import Eval
init_logger
✓ import braintrust
braintrust.init_logger(...)
wrap_openai
✓ import braintrust
client = braintrust.wrap_openai(openai.OpenAI(...))
braintrust_langchain
✓ from braintrust import LangchainCallback
✗ import braintrust_langchain
The braintrust-langchain package is deprecated; its functionality is now integrated directly into the main 'braintrust' package. [3]
This quickstart demonstrates how to run a simple evaluation using the `braintrust.Eval` class. It defines a basic task and a scoring function, then executes the evaluation. The `BRAINTRUST_API_KEY` environment variable is required for the results to be logged to your Braintrust dashboard. [2, 7]
import os
from braintrust import Eval
def is_equal(expected, output):
return expected == output
# Ensure BRAINTRUST_API_KEY is set in your environment variables.
# For local execution: export BRAINTRUST_API_KEY="<YOUR_API_KEY>"
# For production: Use secrets management or similar.
api_key = os.environ.get('BRAINTRUST_API_KEY', '')
if not api_key:
print("Warning: BRAINTRUST_API_KEY environment variable not set. Evaluation will not be logged to Braintrust.")
# In a real scenario, you might raise an error or handle accordingly.
# The Eval function itself implicitly uses the API key from the environment
# when .run() is called or when integrated with the Braintrust CLI.
Eval(
"Say Hi Bot",
data=lambda: [
{"input": "Foo", "expected": "Hi Foo"},
{"input": "Bar", "expected": "Hello Bar"},
],
task=lambda input: "Hi " + input,
scores=[is_equal],
).run()
print("Evaluation complete. Check your Braintrust dashboard.")
braintrust --version
Debug
Known issues
breakingStarting with v0.4.0, Braintrust Python SDK requires Python 3.10 or higher. Older Python versions are no longer supported. [17]fixUpgrade your Python environment to 3.10 or newer.
affects: <0.4.0
deprecatedThe separate `braintrust-langchain` and `braintrust-adk` packages are deprecated. Their functionality for LangChain and Google ADK integrations has been moved into the main `braintrust` package. [3]fixUninstall the deprecated packages and use the latest `braintrust` package, which includes the integration directly. E.g., `pip install "braintrust[openai-agents]"` for agent integrations. [2, 3]
affects: All versions of braintrust-langchain/braintrust-adk
gotchaAuthentication to Braintrust requires an API key, which must be set as the `BRAINTRUST_API_KEY` environment variable. Without this, operations like logging traces or running evaluations will not connect to your Braintrust project. [2, 9, 12]fixSet the `BRAINTRUST_API_KEY` environment variable in your execution environment. For example: `export BRAINTRUST_API_KEY="<YOUR_API_KEY>"`.
affects: All
gotchaFor defining custom scoring functions in evaluation workflows, the `autoevals` package is frequently used alongside `braintrust`. If you encounter 'LevenshteinScorer not found' or similar errors, it's likely due to missing `autoevals`. [7, 14]fixInstall `autoevals` via `pip install autoevals`.
affects: All
gotchaWhen integrating with Temporal Workflows, the Braintrust logger (`braintrust.init()`) must be initialized *before* creating your Temporal Worker to ensure proper span connection and traceability. [12]fixCall `braintrust.init_logger()` at the earliest possible point in your application startup, preceding Temporal Worker initialization.
affects: All
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'braintrust'
The 'braintrust' Python package is not installed in the current Python environment or the environment is not activated.
fixInstall the Braintrust SDK using pip: `pip install braintrust`.
braintrust_api.APIStatusError: 401 Unauthorized
The Braintrust API key (BRAINTRUST_API_KEY) is either missing, incorrect, or lacks the necessary permissions to perform the requested operation.
fixEnsure the `BRAINTRUST_API_KEY` environment variable is correctly set with a valid API key, or pass the `api_key` argument when initializing the Braintrust client.
braintrust_api.APIConnectionError
The Braintrust SDK was unable to establish a connection with the Braintrust API, possibly due to network issues, DNS problems, firewall restrictions, or a timeout.
fixVerify your internet connection, check firewall settings to ensure access to `api.braintrust.dev` (or your configured Braintrust API URL), and ensure there are no proxy issues.
ValueError: Must specify at least one of project or project_id
The `braintrust.init()` function was called without providing either the `project` name or a `project_id` argument, one of which is required.
fixProvide a `project` name (e.g., `braintrust.init(project='My Project Name')`) or a `project_id` when calling `braintrust.init()`.
braintrust_api.APIStatusError: 429 Too Many Requests
Your application has exceeded the rate limits imposed by the Braintrust API for the given organization and endpoint.
fixImplement exponential backoff and retry logic in your application, or reduce the frequency and volume of API calls to stay within the rate limits.
Upgrade
Version history
0.35.0latest on PyPI · released Aug 27, 2026
Audit
Dependencies
pythonrequiredMinimum Python version required.
autoevalsoptionalCommonly used for defining scorers in evaluation workflows. [7, 14]
orjsonoptionalFor faster JSON serialization with the 'performance' extra. [2]
openaioptionalRequired for integrating with OpenAI models using `braintrust.wrap_openai()`. [14]