Netlify environment variables allow you to configure your site’s build and functionality based on different parameters and deploy contexts.
This page describes environment variable options, how to declare environment variables, and how you might use environment variables with Netlify.
Netlify offers a few different options for how you can use and configure environment variables:
- There are two types of environment variables: shared environment variables that are available to all sites in your team and site environment variables set for specific sites. Site environment variables can override shared environment variables.
- Environment variables are available to builds, functions, injected snippets, and more depending on where you declare them.
- Environment variables are available for use across different deploy contexts —
branch deploy, and
- Netlify provides a set of configuration variables and read-only variables for use during the build process.
- There is a sensitive variable policy that you can configure to control access to sensitive variables.
- You can use the Netlify CLI to access and modify environment variables stored on Netlify.
# Environment variable options
Netlify supports two ways of setting and storing environment variables — with the Netlify UI or CLI, or with a Netlify configuration file. Depending on which method you use, there are different environment variable options available.
We recommend using the Netlify UI or CLI, where possible, to avoid storing sensitive values in your repository.
|Netlify UI or CLI||Netlify configuration file|
|Stored on Netlify||✓|
|Stored in your repository||✓|
|Set site environment variables||✓||✓|
|Set shared environment variables||✓|
|Set a single value that is available to all deploy contexts||✓||✓|
|Set a different value for each deploy context||✓|
|Available to builds||✓||✓|
|Available to serverless functions||✓|
|Available to snippet injection||✓||✓|
|Available to forms||✓|
|Available to signed proxy redirects||✓|
New environment variable options with the Netlify UI, CLI, and API
If you’re looking for more customizable options, opt in to the new environment variables beta experience and migrate your site to the new secrets store. Once you migrate, you can use the Netlify UI, CLI, and API to create environment variables with specific scopes and a value for each deploy context.
There are a few overrides to be aware of:
- Environment variables set in
netlify.tomloverride environment variables set on Netlify using the Netlify UI or CLI.
- Site environment variables override shared environment variables.
- If you use the Netlify configuration file to set environment variables for different deploy contexts, the deploy context precedence rules apply.
The following limitations apply for environment variables:
- Reserved variable names. Netlify offers some read-only build environment variables that are reserved key names. You can’t override these variables or their values.
- Character and value limits. Keys can contain up to 128 characters. Values used by functions should fall within AWS’s environment property limits.
- Shared variable access limitations. Only team Owners can read and edit shared environment variable values.
- Unlinking repositories clears variables. When you unlink a Git repository, all site environment variables set in the Netlify UI are deleted.
# Create environment variables
You can create environment variables with the Netlify UI or CLI, or with a Netlify configuration file.
To apply environment variable changes, build and deploy.
Environment variable changes require a build and deploy to take effect.
# Create variables with the Netlify UI or CLI
When you create environment variables using the Netlify UI or CLI, 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 and vice versa.
Be aware that variables set in a Netlify configuration file override variables set with the Netlify UI or CLI.
# Site environment variables
There are two ways to create site environment variables:
- In the Netlify UI, create variables under Site settings > Build & deploy > Environment > Environment variables.
- With the Netlify CLI, use
env:setto create or update a site environment variable, and
env:importto import from a
envfile. Review our Get Started with Netlify CLI guide to learn more.
Site environment variables override shared variables set at the team level.
# Shared environment variables
This feature may not be available on all plans.
Create shared environment variables in the Netlify UI, under Team settings > Sites > Global site settings > Shared environment variables.
Variables set at the team level are shared by all sites owned by the team. Only team Owners can read or access shared environment variables. Site environment variables override shared environment variables.
# Create variables with a Netlify configuration file
You can create site environment variables with a Netlify configuration file (
netlify.toml) stored in your repository. This file-based configuration method allows you to set different environment variables for different deploy contexts.
netlify.toml is stored in your repository, we recommend setting sensitive values in the Netlify UI instead, where possible.
Variables set in a configuration file override variables set with the Netlify UI or CLI.
# 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 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 assign “public” versions of your variables under the
deploy-previewcontext in your Netlify configuration file.
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 > Build & deploy > Environment > Sensitive variable policy.
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.
# Use environment variables
Once you’ve created environment variables, there are many different ways you can use them:
- Use environment variables during the build process — such as in the
netlify.toml, to install private npm modules, in Node.js script files, and in build plugins.
- Use a custom script or framework-specific variables to copy values into the site code during the build process, for use while your site runs.
- Use a function to access values during runtime.
- Use variables for spam prevention with forms or to specify signed proxy redirects.
- Use snippet injection to access values during post-processing.
If you inject values into the site using a build script or snippet injection, make sure to only include non-sensitive values.
- Build environment variables
- Verified Support Guide on how to use build environment variables
- Get started guide - use environment variables with functions
- Injecting environment variable values in your
- Environment variables for different deploy contexts
- Deploy environment variables
- Deploy to Netlify button - pre-fill environment variables
- Environment variables for signed proxy redirects
- Gatsby environment variables
- Hugo version environment variable
- Node.js functions runtime settings
Did you find this doc useful?
Your feedback helps us improve our docs.