Build environment variables

Netlify environment variables are accessible during your build. This allows you to change behaviors based on deploy parameters or to include information you don't want to save in your repository, such as API keys.

Declare variables

You can create your own environment variables via the following channels:

  • In the Netlify configuration file. File-based configuration allows you to set different environment variables for different deploy contexts. Variable values set in the configuration file will override values set in the UI.
  • In your site dashboard under Settings > Build & deploy > Environment > Environment variables. Variable values set under site settings will override the team-level settings.
  • In team settings, under Settings > Sites > Global site settings > Shared environment variables. Variables set at the team level are shared by all sites owned by the team. These can be overridden by settings at the site level. (This feature may not be available on all plans.)

Environment variables set in the UI are also accessible in other environments associated with your site, including serverless functions at runtime, snippet injection during post processing, and more.

Netlify configuration variables

By setting custom values for certain reserved environment variables, you can change some aspects of your build, such as language and dependency versions. Links in the variable descriptions below provide more information about requirements, defaults, and accepted values.

Read-only variables

In addition to the variables you choose to declare, Netlify has a number of pre-defined variables built in. The following variables are automatically set for your builds, and their values are not changeable.

Build metadata

  • NETLIFY: Always true. Can be used to check if the build is running on Netlify.
  • BUILD_ID: Unique ID for the build; for example: 5d4aeac2ccabf517d2f219b8.
  • CONTEXT: Name of the build's deploy context. It can be production, deploy-preview or branch-deploy.
  • _system_arch: The system architecture of the current build image; for example, x86_64.
  • _system_version: The version of Ubuntu Linux running in the current build image; for example, 16.04.

Git metadata

  • REPOSITORY_URL: URL for the linked Git repository.
  • BRANCH: Reference to check out after fetching changes from the Git repository. Can be useful for split testing.
  • HEAD: Name of the head branch received from a Git provider.
  • COMMIT_REF: Reference ID (also known as 'SHA' or 'hash') of the commit we're building.
  • CACHED_COMMIT_REF: Reference ID (also known as 'SHA' or 'hash') of the last commit that we built before the current build.
  • PULL_REQUEST: Whether the build is from a pull/merge request (true) or not (false).
  • REVIEW_ID: If from a pull/merge request, the ID of the request and the Deploy Preview it generated (e.g. 1211). These two numbers will always match. (For example, deploy-preview-12 is for PR #12 in your repository.)

Deploy URLs and metadata

  • URL: This URL represents the main address to your site. It can be either a Netlify subdomain or your own custom domain if you set one; for example, or
  • DEPLOY_URL: This URL represents the unique URL for an individual deploy. It starts with a unique ID that identifies the deploy; for example,
  • DEPLOY_PRIME_URL: This URL represents the primary URL for an individual deploy, or a group of them, like branch deploys and Deploy Previews; for example, or
  • DEPLOY_ID: Unique ID for the deploy; for example, 578ab634d6865d5cf960d620. Matches the beginning of DEPLOY_URL.
  • NETLIFY_IMAGES_CDN_DOMAIN: If image compression post processing is enabled, the base URL used for all processed images; for example,

Build hook metadata and payload

If your build is triggered from a custom build hook, Netlify also has three build-hook-specific variables:

  • INCOMING_HOOK_TITLE: Title of the build hook.
  • INCOMING_HOOK_URL: URL of the build hook.
  • INCOMING_HOOK_BODY: The payload of the request sent to the build hook URL.