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.

SQLite local store

By default every finished run is written as JSON. Set DEEPEVAL_LOCAL_STORE=sqlite (or run deepeval set-local-store sqlite --save=dotenv) to keep a queryable history of runs in a single SQLite database instead. A full comparison of the two backends, where each file lands, and how to export the database to other platforms is here.

export DEEPEVAL_LOCAL_STORE=sqlite
deepeval test run test_llm_app.py
# Test run saved to .deepeval/deepeval.db (run id 3)

The database lives at deepeval.db inside DEEPEVAL_RESULTS_FOLDER (or DisplayConfig(results_folder=...)) when set, otherwise inside the .deepeval cache folder. No JSON files are written in this mode, and nothing is uploaded — it is purely local storage.

Each run is broken out into five tables — test_runs, test_cases, traces, spans, metric_data — so you can query across runs with plain SQL, while the test_runs row keeps the complete serialized run in payload_json (and, with DEEPEVAL_SQLITE_INCLUDE_ROW_JSON=1, so does every test case, trace and span row). The exact CREATE TABLE statements are listed here; the schema is identical in both SDKs, so a Python and a TypeScript project can share one deepeval.db.

For example, to track a metric's average across every run:

sqlite3 .deepeval/deepeval.db \
  "SELECT r.id, r.identifier, m.name, round(avg(m.score), 3)
   FROM metric_data m JOIN test_runs r ON r.id = m.test_run_id
   GROUP BY r.id, m.name ORDER BY r.id"

Stored runs can be listed and opened in the deepeval inspect TUI with the --list and --run-id <id> flags, or loaded back in code:

from deepeval.sqlite_store import list_test_runs, load_test_run, resolve_db_path

db = resolve_db_path()                 # honours DEEPEVAL_RESULTS_FOLDER
runs = list_test_runs(db, limit=10)    # newest first, summary columns only
run_id, test_run = load_test_run(db)   # latest run as a `TestRun`

The store uses only Python's built-in sqlite3 module, so there is nothing extra to install and it works the same on macOS, Linux, Windows, and CI.

Writes are single transactions with a 30-second busy timeout, and any storage failure (read-only filesystem, locked database) is reported as a warning rather than failing the evaluation. DEEPEVAL_FILE_SYSTEM=READ_ONLY disables it entirely, like every other local write.

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.