Skip to main content
Phoenix’s Python SDK is modular by design, allowing you to install only what you need. Each package serves a specific purpose and can be used independently or together.

Phoenix Client

API for the Phoenix platform

Phoenix OTEL

OpenTelemetry tracing with Phoenix defaults

Phoenix Evals

LLM evaluation and metrics toolkit

OpenInference

Instrumentation and tracing helpers

Installation

Install all packages together or individually based on your needs:

Environment Variables

Phoenix’s SDKs, the px CLI, and MCP read their connection settings from environment variables. Two endpoint variables exist — one per concern, usually holding the same URL: Any Phoenix instance that isn’t running on the same machine as your app — a container, a Kubernetes deployment, or a managed host — is reached the same way: point PHOENIX_COLLECTOR_ENDPOINT at its hostname, and supply an API key if it has authentication enabled. That one variable covers tracing, the clients, and the px CLI.
For a self-hosted URL with no path, like this one, Python’s register() exports traces over OTLP/gRPC to port 4317 on the same host. If the deployment does not expose that port, for example behind a reverse proxy or an ingress, pass protocol="http/protobuf" to register(). If you set only one, set PHOENIX_COLLECTOR_ENDPOINT. It configures tracing, and the clients and the px CLI use it for API access too — so one value covers everything. PHOENIX_ENDPOINT is the canonical setting for those client surfaces, and it wins when both are set, but you rarely need it on its own. The fallback does not run both ways in every SDK. API access falls back to PHOENIX_COLLECTOR_ENDPOINT everywhere, but Python trace export does not yet read PHOENIX_ENDPOINT, so setting only PHOENIX_ENDPOINT can leave Python trace export pointed at http://localhost:6006. Set PHOENIX_ENDPOINT as well only when trace ingest and API access live at different URLs. PHOENIX_HOST is not a client setting — on the Phoenix server it is the bind host (e.g. 0.0.0.0, paired with PHOENIX_PORT). Some JS tools still accept it as a last-resort legacy fallback for the base URL, but new configuration should use the variables above.
Keep PHOENIX_ENDPOINT a base URL. The px CLI and the API clients append their own request paths to it.PHOENIX_COLLECTOR_ENDPOINT takes the shape the exporter reading it needs.
  • The TypeScript register() always exports over OTLP/HTTP. It appends /v1/traces when the path is missing.
  • The Python register() picks the transport from the value. A Phoenix Cloud URL or a URL with a path uses OTLP/HTTP, and register() appends /v1/traces when the path is missing. A URL with no path uses OTLP/gRPC to the same host on PHOENIX_GRPC_PORT (default 4317). The protocol argument overrides this choice. See Protocol selection.
Exporters that POST to exactly the URL they are given — @mastra/arize’s ArizeExporter, a bare OTLPTraceExporter — need the full OTLP/HTTP URL. Set PHOENIX_COLLECTOR_ENDPOINT to the /v1/traces-suffixed form, or build that URL in code where the exporter is constructed, the way the Mastra examples do (`${PHOENIX_COLLECTOR_ENDPOINT}/v1/traces`). The px CLI and the API clients strip the suffix when inferring their base URL from it.With Python’s register(), pass protocol="http/protobuf" when the value has a path, or when the gRPC port is not reachable.

Choosing a project

PHOENIX_PROJECT selects the project that project-scoped operations write to and read from. PHOENIX_PROJECT_NAME is a supported alias for the same setting. When both are set, PHOENIX_PROJECT wins and Phoenix logs a one-time conflict warning. If neither is set, the project defaults to "default".

The .env.phoenix file

Instead of exporting variables in every shell, you can drop PHOENIX_-prefixed settings into a .env.phoenix file. The Phoenix SDKs and CLI auto-discover it: starting from the current working directory they walk up toward the filesystem root and load the first .env.phoenix they find (dotenv format).
This is the same file px setup writes: it records both endpoint variables (same value — one server) so trace export and API access are each explicit. A few rules worth knowing:
  • The process environment always wins. A value already set in the environment is never overridden by the file. Watch for endpoint variables exported globally — a PHOENIX_ENDPOINT in your shell profile, or in ~/.claude/settings.json from Claude Code tracing, applies in every directory and will shadow a project’s .env.phoenix. If px or a client is reaching the wrong Phoenix, check echo $PHOENIX_ENDPOINT first. Scope such variables to the session or project that needs them.
  • The filename is .env.phoenix, not .env.
  • Add it to your ignore rules before storing credentials in it — the Phoenix repository already git-ignores .env.phoenix.
  • Opt out by setting PHOENIX_DISCOVER_CONFIG=false (also accepts 0, no, off), which disables file discovery entirely.

Phoenix Client

PyPI Version The Phoenix Client provides a programmatic interface to the Phoenix platform via its REST API. Use it to manage datasets, run experiments, analyze traces, and collect feedback.
  • Prompts — Create, version, and invoke prompt templates with variable substitution
  • Datasets — Build evaluation datasets from DataFrames, CSV files, or dictionaries
  • Experiments — Run evaluations and track experiment results over time
  • Spans — Query and analyze traces with powerful filtering capabilities
  • Annotations — Add human feedback and automated evaluations to spans
  • Projects — Organize your work across multiple AI applications

Usage Guide

Examples and getting started

API Reference

Full API documentation

Phoenix OTEL

PyPI Version Phoenix OTEL provides a lightweight wrapper around OpenTelemetry primitives with Phoenix-aware defaults. It simplifies tracing setup and provides decorators for common GenAI patterns.
  • Zero-config tracing — Enable auto_instrument=True to automatically trace AI libraries
  • Phoenix-aware defaults — Reads PHOENIX_COLLECTOR_ENDPOINT, PHOENIX_API_KEY, and other environment variables
  • Production ready — Built-in batching and authentication support
  • Tracing decorators — @tracer.chain, @tracer.tool, and more for manual instrumentation
  • OpenTelemetry compatible — Works with existing OTel infrastructure

Usage Guide

Examples and getting started

API Reference

Full API documentation

Phoenix Evals

PyPI Version Phoenix Evals provides lightweight, composable building blocks for evaluating LLM applications. It includes tools for relevance scoring, faithfulness detection, toxicity checks, and custom metrics.
  • Model adapters — Works with OpenAI, LiteLLM, LangChain, and other providers
  • Pre-built metrics — Faithfulness detection, relevance, toxicity, and more
  • Input mapping — Powerful binding for complex data structures
  • Native instrumentation — OpenTelemetry tracing for observability
  • High performance — Up to 20x speedup with built-in concurrency and batching

Usage Guide

Examples and getting started

API Reference

Full API documentation

OpenInference

PyPI Version OpenInference provides instrumentation utilities and helpers for tracing AI applications. Use it alongside Phoenix OTEL for decorators, context managers, and data masking capabilities.
  • Decorators — Use @tracer.agent, @tracer.chain, @tracer.tool to trace custom functions
  • Context managers — Wrap code blocks with using_ helpers for fine-grained control
  • Data masking — Redact sensitive information from traces with built-in masking utilities
  • Framework instrumentors — Auto-trace OpenAI, LangChain, LlamaIndex, Anthropic, and more

Usage Guide

Examples and getting started

GitHub

Source code and documentation