Environment variables and serverless functions

Netlify environment variables are accessible when you run Netlify Functions (including scheduled functions, background functions, and On-demand Builders). This allows you to securely provide sensitive values for your serverless functions to use while they run – values such as API keys and tokens.

This page describes how to create environment variables for serverless functions, the specific read-only variables that are available during runtime, and how to access environment variables within your serverless functions.

Declare variables

You can declare and set environment variables using the Netlify UI, CLI, or API for use with serverless functions. If you have the option to set specific scopes for your environment variables, the scope must include Functions to be available to serverless functions during runtime.

Note that environment variables declared in a Netlify configuration file (netlify.toml) are not available to serverless functions.

Visit the environment variables overview to learn more about environment variables at Netlify.

Want to configure your serverless functions? Use build environment variables

This document focuses on how to use environment variables in your serverless functions during runtime. If you need to set specific variables to configure how Netlify builds your serverless functions, leverage build environment variables instead.

Netlify configuration variables

By setting custom values for certain reserved environment variables, you can change some aspects of your serverless functions.

• AWS_LAMBDA_JS_RUNTIME: value that sets the Node.js runtime version for Netlify Functions. This environment variable must be set using the Netlify UI, CLI, or API, and not with a Netlify configuration file (netlify.toml).

Netlify read-only variables

While Netlify offers a number of configuration and read-only environment variables during the build step, only the following read-only variables are available to serverless functions during runtime.

Note that read-only environment variables are reserved in Netlify’s system. You can’t set or override these values manually.

• SITE_NAME: name of the site, its Netlify subdomain; for example, petsof.
• SITE_ID: unique ID for the site; for example, 1d01c0c0-4554-4747-93b8-34ce3448ab95.
• URL: URL representing the main address to your site. It can be either a Netlify subdomain or your own custom domain if you set one; for example, https://petsof.netlify.app orhttps://www.petsofnetlify.com.

Also available are the read-only, reserved runtime environment variables provided by AWS.

Note that other Netlify read-only environment variables are available when you use Netlify Dev to help with local development, but only the above subset are available in all other environments.

Overrides and limitations

The general environment variable overrides and limitations apply to environment variables used with serverless functions. Here are some additional limitations to note:

• Environment variables declared in a Netlify configuration file (netlify.toml) are not available to serverless functions.
• Changes to environment variables for serverless functions require a build and deploy to take effect.
• Because Netlify Functions are powered by AWS Lambda, AWS’s environment property limits apply to environment variables used with Netlify Functions. If you have the option to set specific scopes for your environment variables, you can adjust the scope of your variables to avoid hitting these limits.
• In addition to Netlify’s read-only variables, AWS’s reserved environment variables are reserved in Netlify’s system. You can’t create environment variables with a key that’s reserved by a read-only variable. You also can’t set or override these values manually.

Access environment variables

Once you declare environment variables for the Functions scope, you can access them in your serverless functions using the format process.env.VARIABLE_NAME.

Want to use build environment variables in your serverless functions?

Unlike environment variables set for the Functions scope, variables set for the Build scope are only available during the build step for your site. If you would like to use build environment variables in your serverless functions, you’ll need to embed their values into the serverless functions while your site is building. You can write a script to do this or use a plugin like Netlify Bundle ENV.

TypeScript

import type { Handler, HandlerEvent, HandlerContext } from "@netlify/functions";

const handler: Handler = async (event: HandlerEvent, context: HandlerContext) => {

const value = process.env.MY_IMPORTANT_VARIABLE;

return {
statusCode: 200,
body: JSON.stringify({ message: `Value of MY_IMPORTANT_VARIABLE is ${value}.`}),
};
};

export { handler };

JavaScript

exports.handler = async function (event, context) {
  const value = process.env.MY_IMPORTANT_VARIABLE;

  return {
    statusCode: 200,
    body: JSON.stringify({ message: `Value of MY_IMPORTANT_VARIABLE is ${value}.` }),
  };
};

More resources

• Environment variables overview
• Build environment variables
• Environment variables and edge functions
• Verified Support Guide on using an SSH key via environment variables during build
• Netlify blog: How to use really long environment variables in Netlify Functions