TemperStack
Find Tools
Intermediate12 min readUpdated Mar 13, 2026

How to configure environment variables on Netlify

Quick Answer

Set environment variables on Netlify using the UI (Site settings > Environment variables), CLI (netlify env:set), 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 $VAR_NAME in builds. Test locally with netlify dev. Import from .env files for bulk setup.

Prerequisites

  1. A Netlify account and site connected to a Git repository
  2. Netlify CLI installed via <code>npm install -g netlify-cli</code>
  3. Basic knowledge of your build tool and framework
  4. A local .env file for development (never commit secrets)
  5. Access to site settings in Netlify dashboard
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.
Tip
Use uppercase names with underscores for consistency, and prefix client-side vars like REACT_APP_ 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.
Tip
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.
Tip
Use Branch with wildcards (e.g., release/*) 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.
Tip
Secrets are masked in UI and logs but still accessible via process.env 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.
Tip
Never commit .env to Git; use .gitignore 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.
Tip
CLI overrides UI vars locally; use netlify dev 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.
Tip
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.
Tip
For frameworks, embed in build command, e.g., REACT_APP_API=$API_KEY npm run build.
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.
Tip
Local dev respects UI/CLI vars and deploy contexts like Local development.

Troubleshooting

Variables undefined during build (e.g., API key missing error)
Verify Builds 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 Functions 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 Local development context in UI, use netlify dev, and add CONTEXT=dev to local .env.
Client-side frameworks (React/Next.js) can't access vars
Use framework prefixes (e.g., REACT_APP_) and embed in build command for bundling.

Related Guides

More Netlify Tutorials

How to deploy site from GitHub

How to install Netlify CLI

How to set up custom domain

How to configure build settings

Other Tool Tutorials

V

Vercel Tutorials

Ready to get started with Netlify?

Put this tutorial into practice. Visit Netlify and follow the steps above.

Visit Netlify →