Environment variables

Environment variables can control Claude Code behavior such as model selection, authentication, request routing, and feature toggles. Many of the same behaviors can also be configured through a settings file field, a CLI flag, or an in-session command like /model. This page covers how to:

Set environment variables in your shell or in a settings file
Check which value applies when a behavior can be set more than one way
Look up the variables Claude Code reads

Set environment variables

A variable you set in your shell lasts for that terminal session, while a variable in a settings file applies every time claude runs.

In your shell

Set the variable before launching claude:

macOS, Linux, WSL
Windows PowerShell
Windows CMD

export API_TIMEOUT_MS="1200000"
claude

To set it for every session, add the export line to ~/.bashrc, ~/.zshrc, or your shell’s profile file.

$env:API_TIMEOUT_MS = "1200000"
claude

To set it for every session, run [Environment]::SetEnvironmentVariable("API_TIMEOUT_MS", "1200000", "User") and open a new terminal.

set API_TIMEOUT_MS=1200000
claude

To set it for every session, run setx API_TIMEOUT_MS "1200000" and open a new terminal.

The assignment line prints nothing on success, so confirm the variable is set by printing it in the same shell before you run claude:

macOS, Linux, WSL
Windows PowerShell
Windows CMD

echo $API_TIMEOUT_MS

echo $env:API_TIMEOUT_MS

echo %API_TIMEOUT_MS%

In settings files

Add variables under the env key in a settings.json file, creating the file if it doesn’t exist. Claude Code reads them directly from the file, so they take effect no matter how claude was launched. A running session applies new and changed values to its environment when you save the file, but a feature that reads its variables once at startup, such as OpenTelemetry monitoring, keeps its startup values until you relaunch. Removing a variable from the file doesn’t unset it in a running session; the removal takes effect the next time you launch claude.

~/.claude/settings.json

{
  "env": {
    "API_TIMEOUT_MS": "1200000",
    "BASH_DEFAULT_TIMEOUT_MS": "300000"
  }
}

The file you choose controls who the variables apply to:

File	Applies to
`~/.claude/settings.json`	You, in every project
`.claude/settings.json`	Everyone working in the project, checked into source control
`.claude/settings.local.json`	You, in this project only, gitignored when Claude Code saves a setting to it; add it to your gitignore if you create it by hand
Managed settings	Everyone in your organization, deployed by an admin

See Settings files for where each file lives and Settings precedence for how they combine when more than one sets the same variable.

Precedence

Some behaviors have both an environment variable and a dedicated settings key. If you set both, the environment variable takes precedence. For example, ANTHROPIC_MODEL overrides the model setting, and CLAUDE_CODE_AUTO_CONNECT_IDE overrides autoConnectIde. Claude Code uses the settings key only when the environment variable is unset. When the same variable is set in both your shell and a settings file env block, the settings file value applies. Claude Code writes each env entry into the process environment at startup and again when the file changes, replacing the value inherited from the shell. A few variables are special-cased; the env setting lists the exceptions. In a settings file you can set a variable but you can’t remove one. To override a variable you can’t unset, such as a stale CLAUDE_CODE_USE_VERTEX exported by a shell profile you don’t control, set it to an empty string in the env block: "CLAUDE_CODE_USE_VERTEX": "". Claude Code treats the empty value as unset for provider selection. Subprocesses still inherit the empty value. Between settings files, env values follow settings precedence, so a managed settings entry overrides the same variable in user or project settings. How an environment variable interacts with CLI flags and in-session commands varies per feature: --model and /model override ANTHROPIC_MODEL, while CLAUDE_CODE_EFFORT_LEVEL overrides /effort. When a variable interacts with another configuration source, its row in the Variables list states the precedence or links to the page that documents it. Claude Code reads shell environment variables at startup, so changes to them take effect the next time you launch claude. Variables set under the env key in settings files are reapplied to a running session when the file changes, with the startup-only exception described in In settings files.

Variables

Numeric variables such as timeouts, token budgets, and retry counts accept scientific notation and digit-separator spellings in addition to plain digits, except where a variable’s row notes it takes plain digits only. For example, Claude Code reads 2e3 as 2000 and 64_000 as 64000. Before v2.1.211, these spellings could silently set a much smaller value, such as 1e6 setting a timeout to 1.

For variables that turn a behavior on or off, set 1 or true to turn it on and 0 or false to turn it off, in any casing.Some variables read only whether you set them at all, so any non-empty value including 0 turns the behavior on, and you turn the behavior off by unsetting the variable or setting it to an empty value. These variables work that way:

CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC
DISABLE_TELEMETRY
DISABLE_ERROR_REPORTING
CLAUDE_CODE_TMUX_TRUECOLOR
FALLBACK_FOR_ALL_PRIMARY_MODELS
IS_DEMO

One other variable has its own rule: FORCE_HYPERLINK reads a number, so only 0 turns it off. Each variable’s row also states its own rule.

Variable	Purpose
`ANTHROPIC_API_KEY`	API key sent as `X-Api-Key` header. When set, this key is used instead of your Claude Pro, Max, Team, or Enterprise subscription even if you are logged in. In non-interactive mode (`-p`), the key is always used when present. In interactive mode, you are prompted to approve the key once before it overrides your subscription. To use your subscription instead, run `unset ANTHROPIC_API_KEY`
`ANTHROPIC_AUTH_TOKEN`	Custom value for the `Authorization` header (the value you set here will be prefixed with `Bearer` )
`ANTHROPIC_AWS_API_KEY`	Workspace API key for Claude Platform on AWS, generated in the AWS Console. Sent as `x-api-key` and takes precedence over AWS SigV4
`ANTHROPIC_AWS_BASE_URL`	Override the Claude Platform on AWS endpoint URL. Use for custom regions or when routing throug

Reference

Glossary

Set environment variables

In your shell

In settings files

Precedence

Variables

​Set environment variables

​In your shell

​In settings files

​Precedence

​Variables

Set environment variables

In your shell

In settings files

Precedence

Variables