TensorZero Python Client

2026.5.0 verified Sat May 09 auth: no python

The Python client for TensorZero, an open-source platform for optimizing and evaluating LLM applications. Current version 2026.5.0, requires Python >=3.10. Released approximately monthly.

pip install tensorzero

Common errors

error ModuleNotFoundError: No module named 'tensorzero' ↓

cause Package not installed or installed in wrong environment.

fix

Run pip install tensorzero in the correct Python environment (Python >=3.10).

error ImportError: cannot import name 'Client' from 'tensorzero' ↓

cause The client class was renamed from `Client` to `TensorZeroGateway` in a past breaking change.

fix

Use from tensorzero import TensorZeroGateway instead.

error tensorzero.config.ConfigError: config file not found ↓

cause The gateway requires a configuration file (e.g., `tensorzero.toml`) in the specified path.

fix

Ensure the config file exists and use --config-file with correct path (use **/*.toml for recursive search).

error tensorzero.gateway.GatewayError: inference failed: ... ↓

cause Inference request failed due to invalid input, missing API keys, or provider errors.

fix

Check the response status code and error message. Verify your input schema and ensure provider API keys are set.

Warnings

breaking Version 2026.5.0 changes UI authentication: when gateway requires auth, UI now also requires auth. ↓

fix Ensure your gateway and UI authentication settings are consistent.

breaking Version 2026.4.1 defaults to async observability writes, reducing tail latency. ↓

fix To restore synchronous writes, set `observability.async_writes = false` in gateway config.

breaking Version 2026.2.2 changes config-file globbing: single-level wildcards no longer match across directories. ↓

fix Use `**` for recursive globbing, e.g., `--config-file **/*.toml`.

breaking Version 2026.2.1 changes default `cache_options.enabled` from `write_only` to `off`. ↓

fix If you rely on caching, set `cache_options.enabled = 'write_only'` explicitly.

deprecated Legacy inference evaluations format (flat under `[evaluators]`) is deprecated since 2026.3.4. ↓

fix Nest evaluators under functions: `[functions.my_func.evaluators.exact_match]`.

deprecated The `model_provider_name` filter for `extra_body` and `extra_headers` was removed in 2026.3.1. ↓

fix Use `model_name` and `provider_name` instead.

Imports

TensorZeroGateway
wrong
```
from tensorzero import Client
```
correct
```
from tensorzero import TensorZeroGateway
```
The main client class was historically named 'Client' but is now 'TensorZeroGateway' in modern versions.
inference
```
from tensorzero import inference
```
Direct import of inference function

Quickstart

Initialize TensorZero client and make a simple inference.

from tensorzero import TensorZeroGateway

# Initialize client pointing to your TensorZero gateway
client = TensorZeroGateway(base_url='http://localhost:3000')

# Make an inference
response = client.inference(
    function_name='chatbot',
    input={
        'messages': [
            {'role': 'user', 'content': 'Hello!'}
        ]
    }
)

print(response['output']['content'])