N Netlify

How to configure environment variables on Netlify

intermediate 12 min read Updated 2026-03-13
Quick Answer

Set environment variables on Netlify using the UI (Site settings > Environment variables), CLI (<code>netlify env:set</code>), or netlify.toml; select Builds scope for build access and Functions for runtime, choose deploy contexts like Production or Branch, mark secrets appropriately, and access via <code>$VAR_NAME</code> in builds. Test locally with <code>netlify dev</code>. Import from .env files for bulk setup.

Prerequisites

  • A Netlify account and site connected to a Git repository
  • Netlify CLI installed via <code>npm install -g netlify-cli</code>
  • Basic knowledge of your build tool and framework
  • A local .env file for development (never commit secrets)
  • Access to site settings in Netlify dashboard

Step-by-Step Instructions

1

Access Environment Variables in Netlify UI

Log in to your Netlify dashboard, select your site, and navigate to Project configuration or Site settings > Build & Deploy > Environment variables. Click the button to add a new variable. Enter the key name (e.g., API_KEY) and value in the respective fields.
Use uppercase names with underscores for consistency, and prefix client-side vars like <code>REACT_APP_</code> for frameworks.
2

Configure Scopes for Builds and Functions

Set the Scopes to include Builds for availability during the build process. For serverless functions or runtime access, also select Functions. Variables in netlify.toml are not available to functions, so use UI/CLI/API for function vars.
Functions require explicit Functions scope; Builds scope alone won't make vars available at runtime.
3

Select Deploy Contexts

Choose Deploy contexts where the variable applies: Production for live site, Deploy Previews for PR previews, Branch deploys for branches, Local development for CLI, or specific Branch patterns like staging or release/*. This ensures context-specific values.
Use Branch with wildcards (e.g., <code>release/*</code>) to target multiple related branches efficiently.
4

Mark Sensitive Values as Secrets and Save

For API keys or secrets, toggle the option to mark as secret to prevent exposure in logs or builds. Click Save to apply. Trigger a new deploy to test availability.
Secrets are masked in UI and logs but still accessible via <code>process.env</code> in functions.
5

Import Variables from .env File

In Environment variables, select the import option. Paste contents of your local .env file (e.g., 
API_KEY=secretvalue
DB_URL=connectionstring
). Set uniform Scopes and Contexts for all imported vars, then submit.
Never commit <code>.env</code> to Git; use <code>.gitignore</code> and import only for initial setup.
6

Set Variables via Netlify CLI

Install CLI if needed (npm install -g netlify-cli), then run netlify env:set VARIABLE_NAME "value" for single vars or netlify env:import .env for files. Authenticate with netlify login and select your site.
CLI overrides UI vars locally; use <code>netlify dev</code> to test in a production-like environment.
7

Configure via netlify.toml File

Create/edit netlify.toml in repo root with context-specific vars: 
[env]
  [env.production]
    API_KEY = "prodvalue"
  [env.deploy-preview]
    API_KEY = "previewvalue"
. Commit to trigger deploy. Avoid secrets here as it's public.
netlify.toml vars override hierarchy: file > UI/CLI/API, but unavailable to functions.
8

Access Variables in Build Commands

In netlify.toml or UI build settings, use Bash syntax: 
[build]
  command = "echo $MY_VARIABLE && npm run build"
. Vars are available as $VAR_NAME during builds.
For frameworks, embed in build command, e.g., <code>REACT_APP_API=$API_KEY npm run build</code>.
9

Test Locally with Netlify Dev

Run netlify dev to simulate production environment, including functions and builds. Ensure CONTEXT=dev in local .env for accurate testing.
Local dev respects UI/CLI vars and deploy contexts like Local development.

Common Issues & Troubleshooting

Variables undefined during build (e.g., API key missing error)

Verify <strong>Builds</strong> scope is selected and deploy context matches (e.g., not Production-only on Branch deploy). Edit variable and redeploy.

Functions can't access variables at runtime

Add <strong>Functions</strong> scope (UI/CLI/API only; netlify.toml unsupported). Restart functions or redeploy.

Wrong value in specific context (e.g., preview uses prod key)

Set context-specific vars or branches. Check hierarchy: .env > UI/CLI > netlify.toml.

Local dev doesn't see variables

Select <strong>Local development</strong> context in UI, use <code>netlify dev</code>, and add <code>CONTEXT=dev</code> to local .env.

Client-side frameworks (React/Next.js) can't access vars

Use framework prefixes (e.g., <code>REACT_APP_</code>) and embed in build command for bundling.

Visit Netlify View Netlify Pricing