Get started with environment variables

Netlify offers multiple ways to securely create, update, and use environment variables for your sites.

This page outlines how to create and manage site environment variables and shared environment variables, how to use environment variables once they are declared, and how to configure your site’s sensitive variable policy.

# Create environment variables

You can create environment variables with the Netlify UI, CLI, or API, or with a Netlify configuration file. Once you create environment variables, build and deploy your site for the additions to take effect.

# Create variables with the Netlify UI, CLI, or API

When you create environment variables using the Netlify UI, CLI, or API, they are set and securely stored on Netlify. This means you can avoid committing any sensitive values to your repository. The Netlify UI reflects any changes made using the CLI or API and vice versa.

You can create site environment variables and shared environment variables.

Be aware that variables set in a Netlify configuration file override variables set with the Netlify UI, CLI, or API.

Don’t have access to the options outlined below? Migrate your site

If your environment variables are accessible in a different section of the Netlify UI, your site may be using the classic environment variables experience. Migrate your site now to get access to advanced configuration options.

# Site environment variables

There are three ways to create site environment variables:

  • In the Netlify UI, create site variables under Site settings > Environment variables.
  • With the Netlify CLI, use env:set to create a site environment variable, and env:import to import from a .env file. Review our Get Started with Netlify CLI guide to learn more.
  • With the Netlify API, use createEnvVars to create a new site environment variable. Review our Get Started with Netlify API guide to learn more.

If a shared environment variable and a site environment variable exist with the same key name and scope, the site environment variable’s contextual values take precedence in each deploy context. In addition, variables set in the netlify.toml will override those with the same key set in the Netlify UI. Review the overrides section to learn more.

# Shared environment variables

This feature may not be available on all plans.

There are two ways to create shared environment variables:

  • In the Netlify UI, create shared variables under Team settings > Environment variables.
  • With the Netlify API, use createEnvVars to create a new shared environment variable. Review our Get Started with Netlify API guide to learn more.

Variables set at the team level are shared by all sites owned by the team. Only team Owners can read and access shared variables through the Netlify UI, CLI, and API.

If a shared environment variable and a site environment variable exist with the same key name and scope, the site environment variable’s contextual values take precedence in each deploy context. Review the overrides section to learn more.

# Create variables with a Netlify configuration file

You can create site environment variables with a Netlify configuration file stored in your repository. This file-based configuration method allows you to set different environment variables for different deploy contexts .

Note that you can’t set scopes for variables declared using the configuration file. All variables declared using this method have the Builds and Post processing scope.

Since netlify.toml is stored in your repository, we recommend setting sensitive values with the Netlify UI, CLI, or API instead, where possible.

Here is an example of how to declare variables in netlify.toml:

# Production context: all deploys from the Production branch
# set in your site’s Branches settings in the UI will inherit
# these settings. You can define environment variables
# here but we recommend using the Netlify UI for sensitive
# values to keep them out of your source repository.
[context.production]
  publish = "output/"
  command = "make publish"
  environment = { NODE_VERSION = "14.15.3" }

# Here is an example of how to define context-specific
# environment variables. Be mindful when using this
# option and avoid committing sensitive values to public
# source repositories.
[context.deploy-preview.environment]
  NOT_PRIVATE_ITEM = "not so secret"

# Branch Deploy context: all deploys that are not from
# a pull/merge request or from the Production branch
# will inherit these settings.
[context.branch-deploy.environment]
  NODE_ENV = "development"

# Dev context: environment variables set here 
# are available for local development environments 
# run using Netlify Dev. These values can be 
# overwritten on branches that have a more specific 
# branch context configured.
[context.dev.environment]
  NODE_ENV = "development"

# Specific branch context: all deploys from
# this specific branch will inherit these settings.
[context.staging.environment] # “staging” is a branch name
  NODE_ENV = "development"

Variables set in a configuration file override variables set with the Netlify UI, CLI, or API.

# Modify and delete environment variables

There are multiple ways to edit or delete environment variables that you set using the Netlify UI, CLI, or API. Note that only team Owners can read and modify shared variables.

To apply environment variable changes, build and deploy.

Environment variable changes require a build and deploy to take effect.

# Update variables with the Netlify UI

To edit or delete site environment variables:

  1. Navigate to Site settings > Environment variables for site environment variables or to Team settings > Environment variables for shared environment variables.
  2. Filter the list of variables by key name to find the variable you want to modify. Then, select the variable from the list to expand the variable details.
  3. Select Options > Edit or Options > Delete and then follow the prompts to complete your change.

# Update variables with the Netlify CLI or API

You can use the Netlify CLI to update site environment variables and the Netlify API to update both site and shared environment variables.

  • With the Netlify CLI, use env:set to update a site environment variable, env:import to import from an updated .env file, and env:unset to delete a site environment variable and all of its contextual values.
  • With the Netlify API, use updateEnvVar to update all values for an environment variable, setEnvVarValue to update or create a single value for an existing variable, deleteEnvVar to delete a variable and all of its values, or deleteEnvVarValue to delete a specific value.

Review our Get Started with Netlify CLI guide and our Get Started with Netlify API guide to learn more.

# Use environment variables

Once you’ve created environment variables, there are many different ways you can use them:

If you inject values into the site using a build script or snippet injection, make sure to only include non-sensitive values.

# Sensitive variable policy

Some environment variables you may want to keep private. This can pose a challenge for sites connected to public repositories, where anyone can trigger a Deploy Preview by making a pull/merge request from a fork. Deploys from people, automated services, or bots from outside your Netlify team (unrecognized authors) are always treated as untrusted deploys.

Site members’ deploys are trusted

Git provider accounts connected to a site member can trigger deploys without restrictions, even from forks. If a site member’s deploys are being treated as untrusted, make sure they connect their Git provider account to their Netlify user.

Netlify allows you to control whether untrusted deploys can access sensitive environment variables by choosing a sensitive variable policy. The policy is only available for sites connected to public repositories, and it includes the following options:

  • Require approval (default): policy that requires all untrusted deploys to be approved by a site member before the build can start. Deploys awaiting approval can be found at the top of the deploy list on the site Deploys tab. Accepting or rejecting a deploy request does not affect the status of the originating pull/merge request.

    deploy list entry for an untrusted deploy request, including the Deploy Preview number, Git author username, link to review changes, and buttons to accept or reject.

  • Deploy without sensitive variables: policy that lets untrusted deploys build automatically, but variables identified as sensitive will not be passed to the deploy environment. You can adjust your site code to accommodate builds without sensitive variables present, or you can declare “public” variable values for the deploy-preview context.

  • Deploy without restrictions: policy that treats untrusted deploys like any other Deploy Preview, building automatically with all variables present. Use this option only if you are not concerned about the potential exposure of any of your site’s environment variables.

By default, when Netlify detects potentially sensitive environment variables in your site settings, we automatically apply the default setting above, requiring approval for all untrusted deploys.

You can change this policy at any time in Site settings > Environment variables > Site policies. Can’t find this option? Your site might be using the classic environment variables experience. Find the sensitive variable policy under Site settings > Build & deploy > Environment instead.

Sensitive variable policy for GitHub Enterprise Server or GitLab self-managed

Because GitHub Enterprise Server and GitLab self-managed instances enable a higher degree of access control, we treat all repositories from these instances as private. This means you won’t be able to set a sensitive variable policy for a site linked to a GitHub Enterprise Server or GitLab self-managed repository.

# Deploy request notifications

When your sensitive variable policy is set to require approval for all untrusted deploys, you can add deploy notifications to trigger when a deploy request is pending, approved, or rejected. Visit the deploy notifications doc to learn more about the types of notifications available and how to configure them.