Install & Compatibility
Where this runs
tested against v3.5.1 · 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.910 runs
installs and imports cleanly · install 0.0s · import 1.871s · 207.8MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 11.9s · import 1.779s · 199MB
209MB installed
● package 209MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
create_classifier
✓ from phoenix.evals import create_classifier
LLM
✓ from phoenix.evals.llm import LLM
✗ from phoenix.evals import LLM
LLM class is specifically located in the phoenix.evals.llm submodule.
evaluate_dataframe
✓ from phoenix.evals import evaluate_dataframe
This quickstart demonstrates how to set up an LLM-based classification evaluator using the `arize-phoenix-evals` library with an OpenAI model. It covers defining an evaluator with a prompt template and performing evaluations on both simple and nested input data, showcasing input mapping.
import os
from phoenix.evals import create_classifier
from phoenix.evals.llm import LLM
# Set your OpenAI API key from environment variable
os.environ["OPENAI_API_KEY"] = os.environ.get('OPENAI_API_KEY', 'sk-your-openai-key') # Replace with actual key or ensure env var is set
# Create an LLM instance (ensure OPENAI_API_KEY is set in environment)
llm = LLM(provider="openai", model="gpt-4o")
# Create a custom classification evaluator
evaluator = create_classifier(
name="helpfulness",
prompt_template="Rate the response to the user query as helpful or not:\n\nQuery: {input}\nResponse: {output}",
llm=llm,
choices={"helpful": 1.0, "not_helpful": 0.0},
)
# Simple evaluation on a single record
scores = evaluator.evaluate({"input": "How do I reset the device?", "output": "Go to settings > reset."})
print(f"Simple evaluation score: {scores[0].score}, label: {scores[0].label}")
# Evaluation with input mapping for nested data
scores_nested = evaluator.evaluate(
{"data": {"query": "How do I restart the app?", "response": "Close and reopen the application."}},
input_mapping={"input": "data.query", "output": "data.response"}
)
print(f"Nested evaluation score: {scores_nested[0].score}, label: {scores_nested[0].label}")
Debug
Known issues
breakingVersion 3.0.0 of `arize-phoenix-evals` (and Phoenix v14.0.0) deprecates and removes the 'evals 1.0' module and the legacy experiments module. The `/v1/evaluations` REST endpoint has also been removed from the Phoenix server.fixMigrate to the new evaluation APIs and client-side experiments module. Refer to the official Phoenix migration guide for detailed instructions. If interacting with the Phoenix server directly, use the annotations API instead of `/v1/evaluations`.
affects: >=3.0.0
breakingThe legacy `phoenix.session.client.Client` (accessed as `px.Client()`) has been removed in Phoenix v14.0.0. All client interactions now go through `arize-phoenix-client`.fixUpdate your client instantiation from `import phoenix as px; client = px.Client(endpoint=...)` to `from phoenix.client import Client; client = Client(base_url=...)`. The `endpoint` parameter is now `base_url`.
affects: arize-phoenix-evals>=3.0.0 (due to dependency on Phoenix v14.0.0+)
gotchaWhen using LLM-based evaluators, you must separately install the SDK for your chosen LLM vendor (e.g., `openai` for OpenAI models, `langchain` for LangChain integrations). `arize-phoenix-evals` does not bundle these dependencies.fixInstall the required LLM SDK, for example: `pip install openai>=1.0.0`.
affects: All versions
gotchaStarting with `arize-phoenix-evals` 2.12.0, evaluators automatically JSON-serialize structured data (dicts, lists) passed as template variable values. Manually `str()`-ing complex objects is no longer necessary and could lead to incorrect prompt rendering.fixPass structured data directly to the evaluator; manual serialization is now handled.
affects: >=2.12.0
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'phoenix.evals'
The 'phoenix.evals' module is not found because the 'arize-phoenix-evals' package is not installed.
fixInstall the package using 'pip install arize-phoenix-evals'.
ImportError: cannot import name 'LLM' from 'phoenix.evals'
The 'LLM' class is not found in 'phoenix.evals' due to an outdated or incorrect installation.
fixEnsure you have the latest version by running 'pip install --upgrade arize-phoenix-evals'.
TypeError: evaluate_dataframe() missing 1 required positional argument: 'evaluators'
The 'evaluate_dataframe' function is called without the required 'evaluators' argument.
fixProvide the 'evaluators' argument when calling 'evaluate_dataframe', e.g., 'evaluate_dataframe(dataframe=df, evaluators=[relevance_evaluator])'.
AttributeError: module 'phoenix.evals' has no attribute 'FaithfulnessEvaluator'
The 'FaithfulnessEvaluator' is not found in 'phoenix.evals' due to an incorrect import or outdated version.
fixImport 'FaithfulnessEvaluator' from 'phoenix.evals.metrics', e.g., 'from phoenix.evals.metrics import FaithfulnessEvaluator'.
ValueError: LLM provider 'openai' requires an API key
The 'openai' provider is used without setting the required API key.
fixSet the OpenAI API key by assigning it to the 'OPENAI_API_KEY' environment variable, e.g., 'os.environ["OPENAI_API_KEY"] = "your-api-key"'.
Upgrade
Version history
3.5.1latest on PyPI · released Aug 25, 2026
Audit
Dependencies
openaioptionalRequired for LLM-based evaluators using OpenAI models.
arize-phoenix-clientrequiredUsed for interacting with a running Phoenix session (e.g., logging evaluation results or fetching trace data).