Environment Variables

Environment variables hold configuration and secrets — API keys, database URLs, feature flags — kept out of your source code. On Vercel they're scoped per environment, so the same variable name can hold different values in Production, Preview, and Development.

Scopes

Every variable is assigned to one or more targets:

You can't add a Development variable in the same command as Production or Preview — add development variables separately.

Adding and listing from the CLI

# Add a variable (you'll be prompted for the value and target)
vercel env add API_KEY production

# Add from a file
vercel env add API_KEY production < ./secret.txt

# List all configured variables (names and targets, not values)
vercel env ls

# Remove a variable
vercel env rm API_KEY production

You can also manage them in the dashboard under Project → Settings → Environment Variables.

Sensitive variables

Values can be marked sensitive, meaning they're write-only — once set, they can't be read back through the dashboard or API, only overwritten. Some teams enforce a policy that production and preview writes are always treated as sensitive.

Getting variables onto your machine

This is the part that trips people up, because there are two different commands:

vercel env pull — for framework dev servers

Writes development variables to a local file (default .env.local). Use this when your framework's own dev command (next dev, vite, etc.) reads from .env files:

vercel env pull .env.local

vercel pull — for vercel dev / vercel build

vercel dev and vercel build read from the .vercel/ directory rather than .env files. vercel pull populates that directory with both variables and project settings:

vercel pull
vercel pull --environment=preview   # pull a specific environment

Rule of thumb: vercel env pull when you run your framework's dev server; vercel pull when you run vercel dev or vercel build.

Using them in code

Access variables through the standard runtime mechanism for your language — process.env.API_KEY in Node.js, os.environ in Python, and so on. Client-exposed variables follow your framework's convention (for example, Next.js requires a NEXT_PUBLIC_ prefix to expose a value to the browser).

Related

• Deployments and environments
• CLI: environment variables
• Configuration (vercel.json)