Environment Variables

Environment Variables are key-value pairs configured outside your source code so that each value can change depending on the Environment.

Your source code can read these values to change behavior during the Build Step or during Serverless Function execution.

All values are encrypted at rest and visible to any user that has access to the Project. It is safe to use both non-sensitive and sensitive data, such as tokens.

Changes to Environment Variables are not applied to previous deployments, they only apply to new deployments.

To declare an Environment Variable for your deployment, head to the Environment Variables page of your Project Settings.

The Add New section of the Environment Variables page in the Project Settings.

Enter the desired Name for your Environment Variable. For example, if you are using Node.js and you create an Environment Variable named API_URL, it will be available under process.env.API_URL in your code.

Then, enter the desired Value for your Environment Variable. The value is encrypted at rest so it is safe to add sensitive data like authentication tokens or private keys.

You can then configure which Environments this variable should apply to.

Finally, click Save.

Searching and Filtering

Just below the Add New form is a list of all the Environment Variables for the Project.

You can search for an existing Environment Variable by name using the search input and/or filter by Environment and Git Branch (in the case of the Preview Environment).

Clicking the three dots to the right allows you to edit or delete the Environment Variable.

An example of an Environment Variable with the search and filter inputs above.

Environments

For each Environment Variable, you can select one or more Environments to apply the Variable to:

Preview Environment Variables

Preview Environment Variables are applied to deployments from any Git branch that does not match the Production Branch. When you add a Preview Environment Variable, you can choose to apply to all Preview branches or you can select a specific branch.

When you push to a branch, a combination of Preview Environment Variables and branch-specific variables (if any) will be used. Any branch-specific variables will override other variables with the same name. This means you don't need to replicate all your existing Preview Environment Variables for each branch – you only need to add the values you wish to override.

Adding an Environment Variable to the staging branch.

Development Environment Variables

Environment Variables created for the Development Environment can be downloaded into a local development setup using the vercel env pull command provided by Vercel CLI:

vercel env pull
Downloading Development Environment Variables for Project my-lovely-project
✅ Created .env file [510ms]

Downloading Development Environment Variables with the vercel env pull command.

Running the command will create a .env file in the current directory, which can then be consumed by your framework's Development Command (like next dev).

If you're using vercel dev, there's no need to run vercel env pull, as vercel dev automatically downloads the Development Environment Variables into memory.

For more information on the vercel env command, check out this section.

Integration Environment Variables

Integrations can automatically add Environment Variables to your Project Settings. In that case, the Integration that added the Variable will be displayed:

An Environment Variable added by the Sentry Integration.

Reserved Environment Variables

The following Environment Variable names are reserved and therefore unavailable for use:

• AWS_REGION
• AWS_DEFAULT_REGION
• AWS_ACCESS_KEY_ID
• AWS_SECRET_KEY
• AWS_SECRET_ACCESS_KEY
• AWS_EXECUTION_ENV
• AWS_LAMBDA_LOG_GROUP_NAME
• AWS_LAMBDA_LOG_STREAM_NAME
• AWS_LAMBDA_FUNCTION_NAME
• AWS_LAMBDA_FUNCTION_MEMORY_SIZE
• AWS_LAMBDA_FUNCTION_VERSION
• AWS_SESSION_TOKEN
• NOW_REGION
• TZ
• LAMBDA_TASK_ROOT
• LAMBDA_RUNTIME_DIR

System Environment Variables

Vercel provides a set of Environment Variables that are automatically populated by the System, such as the URL of the Deployment or the name of the Git branch deployed.

To expose them to your Deployments, make sure Automatically expose System Environment Variables is checked in your Project Settings.

Automatically exposing System Environment Variables in the Project Settings.

The following System Environment Variables will be exposed to your Deployments:

Frameworks typically use a prefix in order to expose Environment Variables to the browser.

The following prefixed Environment Variables will be available during the Build Step, based on the Project's selected Framework Preset.