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:

Environment
Description
When selected, the Environment Variable will be applied to your next Production Deployment. To create a Production Deployment, push a commit to the Production Branch or run vercel --prod.
The Environment Variable is applied to your next Preview Deployment. Preview Deployments are created when you push to a branch that is not the Production Branch or run vercel.
The Environment Variable is used when running your project locally with vercel dev or your preferred development command. To download Development Environment Variables, run vercel env pull.

Preview Environment Variables

Note: You need Vercel CLI version 22.0.0 or higher to use the features described in this section.

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

Note: You need Vercel CLI version 21.0.1 or higher to use the features described in this section.

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.

Note: Make sure to read this section about whether you should use vercel dev or not.

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.

Note: Support for Integration Environment Variables was added on April 10th, 2020. Variables added before that date do not have the Integration indication.

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:

Note: If you are using a Framework for your Project, we provide prefixed Environment Variables. You can find a list of those below this table.

Name
Description
VERCEL
An indicator that the app is deployed and running on Vercel. Example: 1.
CI
An indicator that the code is running in a Continuous Integration environment. Example: 1. Note: This Variable is only exposed during Build Step.
VERCEL_ENV
The Environment that the app is deployed an running on. The value can be either production, preview, or development.
VERCEL_URL
The URL of the deployment. Example: my-site-7q03y4pi5.vercel.app.
VERCEL_REGION
The ID of the Region where the app is running. Example: cdg1. Note: This Variable is only exposed during Runtime for Serverless Functions.
VERCEL_GIT_PROVIDER
The Git Provider the deployment is triggered from. Example: github.
VERCEL_GIT_REPO_SLUG
The origin repository the deployment is triggered from. Example: my-site.
VERCEL_GIT_REPO_OWNER
The account that owns the repository the deployment is triggered from. Example: acme.
VERCEL_GIT_REPO_ID
The ID of the repository the deployment is triggered from. Example: 117716146.
VERCEL_GIT_COMMIT_REF
The git branch of the commit the deployment was triggered by. Example: improve-about-page.
VERCEL_GIT_COMMIT_SHA
The git SHA of the commit the deployment was triggered by. Example: fa1eade47b73733d6312d5abfad33ce9e4068081.
VERCEL_GIT_COMMIT_MESSAGE
The message attached to the commit the deployment was triggered by. Example: Update about page.
VERCEL_GIT_COMMIT_AUTHOR_LOGIN
The username attached to the author of the commit that the project was deployed by. Example: johndoe.
VERCEL_GIT_COMMIT_AUTHOR_NAME
The name attached to the author of the commit that the project was deployed by. Example: John Doe.

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.

Name
Description
NEXT_PUBLIC_VERCEL_ENV
The Environment that the app is deployed an running on. The value can be either production, preview, or development.
NEXT_PUBLIC_VERCEL_URL
The URL of the deployment. Example: my-site-7q03y4pi5.vercel.app.
NEXT_PUBLIC_VERCEL_GIT_PROVIDER
The Git Provider the deployment is triggered from. Example: github.
NEXT_PUBLIC_VERCEL_GIT_REPO_SLUG
The origin repository the deployment is triggered from. Example: my-site.
NEXT_PUBLIC_VERCEL_GIT_REPO_OWNER
The account that owns the repository the deployment is triggered from. Example: acme.
NEXT_PUBLIC_VERCEL_GIT_REPO_ID
The ID of the repository the deployment is triggered from. Example: 117716146.
NEXT_PUBLIC_VERCEL_GIT_COMMIT_REF
The git branch of the commit the deployment was triggered by. Example: improve-about-page.
NEXT_PUBLIC_VERCEL_GIT_COMMIT_SHA
The git SHA of the commit the deployment was triggered by. Example: fa1eade47b73733d6312d5abfad33ce9e4068081.
NEXT_PUBLIC_VERCEL_GIT_COMMIT_MESSAGE
The message attached to the commit the deployment was triggered by. Example: Update about page.
NEXT_PUBLIC_VERCEL_GIT_COMMIT_AUTHOR_LOGIN
The username attached to the author of the commit that the project was deployed by. Example: johndoe.
NEXT_PUBLIC_VERCEL_GIT_COMMIT_AUTHOR_NAME
The name attached to the author of the commit that the project was deployed by. Example: John Doe.
Note: System Environment Variables will be populated with an empty string if the value is not applicable, for example when running vercel dev during Development or if the Deployment is not triggered by a Git Commit.