Conceptual
4 min read

Environment Variables

Learn how to use Vercel Environment Variables, which are key-value pairs configured outside your source code that change depending on the environment.
Table of Contents

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 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, go 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.

process.env.API_URL;

Accessing environment variables with supported runtime languages

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.

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.

Developers on all plans can use a total of 64KB in Environments Variables per-Deployment on Vercel. This limit is for all variables combined, and so no single variable can be larger than 64KB. The total size includes any variables configured through the dashboard or the CLI.

With support for 64KB of Environment Variables, you can add large values for authentication tokens, JWTs, or certificates.

Deployments using the following runtimes can support the larger 64KB environment:

  • Node.js
  • Python
  • Ruby
  • Go
  • Java: java11 and java8.al2
  • .NET

In addition, the PHP Community Runtime also supports the 64KB environment.

Vercel also provides support for custom runtimes, through the Build Output API. For information on creating custom runtime support, see the following guides:

While Vercel allows Environment Variables up to a total of 64KB in size, Edge Functions and Edge Middleware are limited to 5KB per Environment Variable.

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

EnvironmentDescription
ProductionWhen 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.
PreviewThe 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.
DevelopmentThe 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.

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.

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.

Review the vercel dev section to learn more about using it.

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

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 MongoDB Integration.

Last updated on March 29, 2024