Environment Variables

deepeval automatically loads environment variables from dotenv files in this order: .env → .env.{APP_ENV} → .env.local (highest precedence). Existing process environment variables are never overwritten—process env always wins.

Boolean flags

Use 1 to enable a boolean environment variable and 0 to disable it. These two values work for every boolean variable on this page, which is why every example uses them.

Rules:

• Values are matched case-insensitively, and any surrounding quotes or whitespace is ignored.
• If a value is unset (or doesn't match a recognized token), deepeval falls back to the setting's default.

Other spellings — true/false, yes/no, y/n, t/f, on/off, enable/disable, enabled/disabled — are also accepted, but prefer 1 and 0.

An invalid value raises at startup, so a typo fails loudly instead of silently falling back.

General Settings

These are the core settings for controlling deepeval's behavior, file paths, and run identifiers.

DEEPEVAL_FILE_SYSTEM also accepts READ-ONLY, READONLY, and RO. Any other value is rejected.

Logging

Retries

These settings control retry and backoff for LLM provider calls.

Timeouts / Concurrency

These options let you tune timeout limits and concurrency for parallel execution and provider calls.

Display / Truncation

These settings control text truncation in logs and displays.

Telemetry / Debug

Model Settings

You can configure model providers by setting a combination of environment variables (API keys, model names, provider flags, etc.). However, we recommend using the CLI commands instead, which will set these variables for you.

Explicit constructor arguments (e.g. OpenAIModel(api_key=...)) always take precedence over environment variables. Token costs resolve in the same order: the constructor argument first, then the provider's *_COST_PER_*_TOKEN variable, then deepeval's built-in price for that model.

You can also set TEMPERATURE to provide a default temperature for all model instances.

Thinking is off unless you set DEEPEVAL_MODEL_THINKING=1, and models without a thinking parameter ignore it. Enabling it raises the default output budget to make room for the reasoning, since providers count thinking tokens against the same max_tokens ceiling as the response — an explicit value still wins, and one too small to hold both raises an error rather than returning a truncated verdict.

Models that always think, such as claude-fable-5, cannot be switched off and reason either way.

Variable Options

When set to 1, USE_{PROVIDER}_MODEL (e.g. USE_OPENAI_MODEL) tells deepeval which provider to use for LLM-as-a-judge metrics when no model is explicitly passed.

Each provider also has its own set of variables for API keys, model names, and other provider-specific options. Expand the sections below to see the full list for each provider.

AWS / Amazon Bedrock

If AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY are not set, the AWS SDK default credentials chain is used.

Variable	Values	Effect
USE_AWS_BEDROCK_MODEL	1 / 0 / unset	Prefer Bedrock as the default LLM provider (where applicable).
AWS_ACCESS_KEY_ID	string / unset	Optional AWS access key ID for authentication.
AWS_SECRET_ACCESS_KEY	string / unset	Optional AWS secret access key for authentication.
AWS_BEDROCK_MODEL_NAME	string / unset	Bedrock model ID (e.g. anthropic.claude-sonnet-4-5-20250929-v1:0).
AWS_BEDROCK_REGION	string / unset	AWS region (e.g. us-east-1).
AWS_BEDROCK_COST_PER_INPUT_TOKEN	float / unset	Optional input-token cost used for cost reporting.
AWS_BEDROCK_COST_PER_OUTPUT_TOKEN	float / unset	Optional output-token cost used for cost reporting.

Anthropic

Variable	Values	Effect
ANTHROPIC_API_KEY	string / unset	Anthropic API key.
ANTHROPIC_MODEL_NAME	string / unset	Optional default Anthropic model name.
ANTHROPIC_COST_PER_INPUT_TOKEN	float / unset	Optional input-token cost used for cost reporting.
ANTHROPIC_COST_PER_OUTPUT_TOKEN	float / unset	Optional output-token cost used for cost reporting.

Azure OpenAI

Azure reuses OPENAI_COST_PER_INPUT_TOKEN and OPENAI_COST_PER_OUTPUT_TOKEN for cost reporting.

Variable	Values	Effect
USE_AZURE_OPENAI	1 / 0 / unset	Prefer Azure OpenAI as the default LLM provider (where applicable).
AZURE_OPENAI_API_KEY	string / unset	Azure OpenAI API key.
AZURE_OPENAI_AD_TOKEN	string / unset	Microsoft Entra ID token, used instead of an API key.
AZURE_OPENAI_ENDPOINT	string / unset	Azure OpenAI endpoint URL.
OPENAI_API_VERSION	string / unset	Azure OpenAI API version.
AZURE_DEPLOYMENT_NAME	string / unset	Azure deployment name.
AZURE_MODEL_NAME	string / unset	Azure model name, used for pricing and reporting.
AZURE_MODEL_VERSION	string / unset	Optional Azure model version (for metadata / reporting).

OpenAI

Variable	Values	Effect
USE_OPENAI_MODEL	1 / 0 / unset	Prefer OpenAI as the default LLM provider (where applicable).
OPENAI_API_KEY	string / unset	OpenAI API key.
OPENAI_MODEL_NAME	string / unset	Optional default OpenAI model name.
OPENAI_COST_PER_INPUT_TOKEN	float / unset	Optional input-token cost used for cost reporting.
OPENAI_COST_PER_OUTPUT_TOKEN	float / unset	Optional output-token cost used for cost reporting.

DeepSeek

Variable	Values	Effect
USE_DEEPSEEK_MODEL	1 / 0 / unset	Prefer DeepSeek as the default LLM provider (where applicable).
DEEPSEEK_API_KEY	string / unset	DeepSeek API key.
DEEPSEEK_MODEL_NAME	string / unset	Optional default DeepSeek model name.
DEEPSEEK_COST_PER_INPUT_TOKEN	float / unset	Optional input-token cost used for cost reporting.
DEEPSEEK_COST_PER_OUTPUT_TOKEN	float / unset	Optional output-token cost used for cost reporting.

Gemini

Variable	Values	Effect
USE_GEMINI_MODEL	1 / 0 / unset	Prefer Gemini as the default LLM provider (where applicable).
GOOGLE_API_KEY	string / unset	Google API key.
GEMINI_MODEL_NAME	string / unset	Optional default Gemini model name.
GEMINI_COST_PER_INPUT_TOKEN	float / unset	Optional input-token cost used for cost reporting.
GEMINI_COST_PER_OUTPUT_TOKEN	float / unset	Optional output-token cost used for cost reporting.
GOOGLE_GENAI_USE_VERTEXAI	1 / 0 / unset	If set, use Vertex AI instead of the Gemini Developer API.
GOOGLE_CLOUD_PROJECT	string / unset	Optional GCP project (Vertex AI).
GOOGLE_CLOUD_LOCATION	string / unset	Optional GCP location/region (Vertex AI).
GOOGLE_SERVICE_ACCOUNT_KEY	string / unset	Optional service account key (Vertex AI).
VERTEX_AI_MODEL_NAME	string / unset	Optional Vertex AI model name, preferred over GEMINI_MODEL_NAME when GOOGLE_GENAI_USE_VERTEXAI is on.

Grok

Variable	Values	Effect
USE_GROK_MODEL	1 / 0 / unset	Prefer Grok as the default LLM provider (where applicable).
GROK_API_KEY	string / unset	Grok API key.
GROK_MODEL_NAME	string / unset	Optional default Grok model name.
GROK_COST_PER_INPUT_TOKEN	float / unset	Optional input-token cost used for cost reporting.
GROK_COST_PER_OUTPUT_TOKEN	float / unset	Optional output-token cost used for cost reporting.

Kimi (Moonshot)

Variable	Values	Effect
USE_MOONSHOT_MODEL	1 / 0 / unset	Prefer Moonshot as the default LLM provider (where applicable).
MOONSHOT_API_KEY	string / unset	Moonshot API key.
MOONSHOT_MODEL_NAME	string / unset	Optional default Moonshot model name.
MOONSHOT_COST_PER_INPUT_TOKEN	float / unset	Optional input-token cost used for cost reporting.
MOONSHOT_COST_PER_OUTPUT_TOKEN	float / unset	Optional output-token cost used for cost reporting.

Local Model

LOCAL_MODEL_BASE_URL points at any OpenAI-compatible server, including LM Studio and vLLM.

Variable	Values	Effect
USE_LOCAL_MODEL	1 / 0 / unset	Prefer the local model adapter as the default LLM provider (where applicable).
LOCAL_MODEL_BASE_URL	string / unset	Base URL for the local model endpoint.
LOCAL_MODEL_API_KEY	string / unset	Optional API key for the local model endpoint (if required).
LOCAL_MODEL_NAME	string / unset	Optional default local model name.
LOCAL_MODEL_FORMAT	string / unset	Optional format hint for the local model integration.

Ollama

Variable	Values	Effect
OLLAMA_MODEL_NAME	string / unset	Optional default Ollama model name.

Portkey

Variable	Values	Effect
USE_PORTKEY_MODEL	1 / 0 / unset	Prefer Portkey as the default LLM provider (where applicable).
PORTKEY_API_KEY	string / unset	Portkey API key.
PORTKEY_MODEL_NAME	string / unset	Optional default model name passed to Portkey.
PORTKEY_BASE_URL	string / unset	Optional Portkey base URL.
PORTKEY_PROVIDER_NAME	string / unset	Optional provider name (Portkey routing).

OpenRouter

Variable	Values	Effect
USE_OPENROUTER_MODEL	1 / 0 / unset	Prefer OpenRouter as the default LLM provider (where applicable).
OPENROUTER_API_KEY	string / unset	OpenRouter API key.
OPENROUTER_MODEL_NAME	string / unset	Optional default model name passed to OpenRouter.
OPENROUTER_BASE_URL	string / unset	Optional OpenRouter base URL.
OPENROUTER_COST_PER_INPUT_TOKEN	float / unset	Optional input-token cost used for cost reporting.
OPENROUTER_COST_PER_OUTPUT_TOKEN	float / unset	Optional output-token cost used for cost reporting.

LiteLLM

Variable	Values	Effect
USE_LITELLM	1 / 0 / unset	Prefer LiteLLM as the default LLM provider (where applicable).
LITELLM_API_KEY	string / unset	Optional API key passed to LiteLLM.
LITELLM_MODEL_NAME	string / unset	Default LiteLLM model name.
LITELLM_API_BASE	string / unset	Optional base URL for the LiteLLM endpoint.
LITELLM_PROXY_API_BASE	string / unset	Optional proxy base URL (if using a proxy).
LITELLM_PROXY_API_KEY	string / unset	Optional proxy API key (if using a proxy).

Embeddings

Variable	Values	Effect
USE_AZURE_OPENAI_EMBEDDING	1 / 0 / unset	Prefer Azure OpenAI embeddings as the default embeddings provider (where applicable).
AZURE_EMBEDDING_DEPLOYMENT_NAME	string / unset	Azure embedding deployment name.
USE_LOCAL_EMBEDDINGS	1 / 0 / unset	Prefer local embeddings as the default embeddings provider (where applicable).
LOCAL_EMBEDDING_API_KEY	string / unset	Optional API key for the local embeddings endpoint (if required).
LOCAL_EMBEDDING_MODEL_NAME	string / unset	Optional default local embedding model name.
LOCAL_EMBEDDING_BASE_URL	string / unset	Base URL for the local embeddings endpoint.

Speech models (TTS/STT)

Text-to-speech and speech-to-text are two independent families used by voice simulation. One USE_*_TTS flag and one USE_*_STT flag can be on at the same time, and each family falls back to OpenAI when no flag is set. Set them with deepeval set-tts and deepeval set-stt.

Variable	Values	Effect
USE_OPENAI_TTS	1 / 0 / unset	Prefer OpenAI for text-to-speech.
USE_ELEVENLABS_TTS	1 / 0 / unset	Prefer ElevenLabs for text-to-speech.
USE_CARTESIA_TTS	1 / 0 / unset	Prefer Cartesia for text-to-speech.
USE_DEEPGRAM_TTS	1 / 0 / unset	Prefer Deepgram for text-to-speech.
DEEPEVAL_TTS_MODEL	string / unset	Model name for the selected TTS provider (defaults to that provider's own default model).
USE_OPENAI_STT	1 / 0 / unset	Prefer OpenAI for speech-to-text.
USE_ELEVENLABS_STT	1 / 0 / unset	Prefer ElevenLabs for speech-to-text.
USE_CARTESIA_STT	1 / 0 / unset	Prefer Cartesia for speech-to-text.
USE_DEEPGRAM_STT	1 / 0 / unset	Prefer Deepgram for speech-to-text.
USE_ASSEMBLYAI_STT	1 / 0 / unset	Prefer AssemblyAI for speech-to-text.
DEEPEVAL_STT_MODEL	string / unset	Model name for the selected STT provider (defaults to that provider's own default model).
ELEVENLABS_API_KEY	string / unset	ElevenLabs API key.
CARTESIA_API_KEY	string / unset	Cartesia API key.
DEEPGRAM_API_KEY	string / unset	Deepgram API key.
ASSEMBLYAI_API_KEY	string / unset	AssemblyAI API key.