Use Lambda environment variables to configure values in code

You can use environment variables to adjust your function's behavior without updating code. An environment variable is a pair of strings that is stored in a function's version-specific configuration. The Lambda runtime makes environment variables available to your code and sets additional environment variables that contain information about the function and invocation request.

Note

To increase security, we recommend that you use AWS Secrets Manager instead of environment variables to store database credentials and other sensitive information like API keys or authorization tokens. For more information, see Create and manage secrets with AWS Secrets Manager.

Environment variables are not evaluated before the function invocation. Any value you define is considered a literal string and not expanded. Perform the variable evaluation in your function code.

You can configure environment variables in Lambda using the Lambda console, the AWS Command Line Interface (AWS CLI), AWS Serverless Application Model (AWS SAM), or using an AWS SDK.

Console

You define environment variables on the unpublished version of your function. When you publish a version, the environment variables are locked for that version along with other version-specific configuration settings.

You create an environment variable for your function by defining a key and a value. Your function uses the name of the key to retrieve the value of the environment variable.

To set environment variables in the Lambda console

1. Open the Functions page of the Lambda console.

2. Choose a function.

3. Choose Configuration, then choose Environment variables.

4. Under Environment variables, choose Edit.

5. Choose Add environment variable.

6. Enter a key and value.

   Requirements

   • Keys start with a letter and are at least two characters.

   • Keys only contain letters, numbers, and the underscore character (_).

   • Keys aren't reserved by Lambda.

   • The total size of all environment variables doesn't exceed 4 KB.

7. Choose Save.

To generate a list of environment variables in the console code editor

You can generate a list of environment variables in the Lambda code editor. This is a quick way to reference your environment variables while you code.

1. Choose the Code tab.

2. Choose the Environment Variables tab.

3. Choose Tools, Show Environment Variables.

Environment variables remain encrypted when listed in the console code editor. If you enabled encryption helpers for encryption in transit, then those settings remain unchanged. For more information, see Securing Lambda environment variables.

The environment variables list is read-only and is available only on the Lambda console. This file is not included when you download the function's .zip file archive, and you can't add environment variables by uploading this file.

AWS CLI

The following example sets two environment variables on a function named my-function.

aws lambda update-function-configuration \
  --function-name my-function \
  --environment "Variables={BUCKET=DOC-EXAMPLE-BUCKET,KEY=file.txt}"

When you apply environment variables with the update-function-configuration command, the entire contents of the Variables structure is replaced. To retain existing environment variables when you add a new one, include all existing values in your request.

To get the current configuration, use the get-function-configuration command.

aws lambda get-function-configuration \
  --function-name my-function

You should see the following output:

{
    "FunctionName": "my-function",
    "FunctionArn": "arn:aws:lambda:us-east-2:111122223333:function:my-function",
    "Runtime": "nodejs20.x",
    "Role": "arn:aws:iam::111122223333:role/lambda-role",
    "Environment": {
        "Variables": {
            "BUCKET": "DOC-EXAMPLE-BUCKET",
            "KEY": "file.txt"
        }
    },
    "RevisionId": "0894d3c1-2a3d-4d48-bf7f-abade99f3c15",
    ...
}

You can pass the revision ID from the output of get-function-configuration as a parameter to update-function-configuration. This ensures that the values don't change between when you read the configuration and when you update it.

To configure a function's encryption key, set the KMSKeyARN option.

aws lambda update-function-configuration \
  --function-name my-function \
  --kms-key-arn arn:aws:kms:us-east-2:111122223333:key/055efbb4-xmpl-4336-ba9c-538c7d31f599

AWS SAM

You can use the AWS Serverless Application Model to configure environment variables for your function. Update the Environment and Variables properties in your template.yaml file and then run sam deploy.

Example template.yaml

AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31
Description: An AWS Serverless Application Model template describing your function.
Resources:
  my-function:
    Type: AWS::Serverless::Function
    Properties:
      CodeUri: .
      Description: ''
      MemorySize: 128
      Timeout: 120
      Handler: index.handler
      Runtime: nodejs18.x
      Architectures:
        - x86_64
      EphemeralStorage:
        Size: 10240
      Environment:
        Variables:
          BUCKET: DOC-EXAMPLE-BUCKET
          KEY: file.txt
      # Other function properties...

AWS SDKs

To manage environment variables using an AWS SDK, use the following API operations.

• UpdateFunctionConfiguration

• GetFunctionConfiguration

• CreateFunction

To learn more, refer to the AWS SDK documentation for your preferred programming language.

Defined runtime environment variables

Lambda runtimes set several environment variables during initialization. Most of the environment variables provide information about the function or runtime. The keys for these environment variables are reserved and cannot be set in your function configuration.

Reserved environment variables

• _HANDLER – The handler location configured on the function.

• _X_AMZN_TRACE_ID – The X-Ray tracing header. This environment variable changes with each invocation.

  • This environment variable is not defined for OS-only runtimes (the provided runtime family). You can set _X_AMZN_TRACE_ID for custom runtimes using the Lambda-Runtime-Trace-Id response header from the Next invocation.

  • For Java runtime versions 17 and later, this environment variable is not used. Instead, Lambda stores tracing information in the com.amazonaws.xray.traceHeader system property.

• AWS_DEFAULT_REGION – The default AWS Region where the Lambda function is executed.

• AWS_REGION – The AWS Region where the Lambda function is executed. If defined, this value overrides the AWS_DEFAULT_REGION.

  • For more information about using the AWS Region environment variables with AWS SDKs, see AWS Region in the AWS SDKs and Tools Reference Guide.

• AWS_EXECUTION_ENV – The runtime identifier, prefixed by AWS_Lambda_ (for example, AWS_Lambda_java8). This environment variable is not defined for OS-only runtimes (the provided runtime family).

• AWS_LAMBDA_FUNCTION_NAME – The name of the function.

• AWS_LAMBDA_FUNCTION_MEMORY_SIZE – The amount of memory available to the function in MB.

• AWS_LAMBDA_FUNCTION_VERSION – The version of the function being executed.

• AWS_LAMBDA_INITIALIZATION_TYPE – The initialization type of the function, which is on-demand, provisioned-concurrency, or snap-start. For information, see Configuring provisioned concurrency or Improving startup performance with Lambda SnapStart.

• AWS_LAMBDA_LOG_GROUP_NAME, AWS_LAMBDA_LOG_STREAM_NAME – The name of the Amazon CloudWatch Logs group and stream for the function. The AWS_LAMBDA_LOG_GROUP_NAME and AWS_LAMBDA_LOG_STREAM_NAME environment variables are not available in Lambda SnapStart functions.

• AWS_ACCESS_KEY, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN – The access keys obtained from the function's execution role.

• AWS_LAMBDA_RUNTIME_API – (Custom runtime) The host and port of the runtime API.

• LAMBDA_TASK_ROOT – The path to your Lambda function code.

• LAMBDA_RUNTIME_DIR – The path to runtime libraries.

The following additional environment variables aren't reserved and can be extended in your function configuration.

Unreserved environment variables

• LANG – The locale of the runtime (en_US.UTF-8).

• PATH – The execution path (/usr/local/bin:/usr/bin/:/bin:/opt/bin).

• LD_LIBRARY_PATH – The system library path (/var/lang/lib:/lib64:/usr/lib64:$LAMBDA_RUNTIME_DIR:$LAMBDA_RUNTIME_DIR/lib:$LAMBDA_TASK_ROOT:$LAMBDA_TASK_ROOT/lib:/opt/lib).

• NODE_PATH – (Node.js) The Node.js library path (/opt/nodejs/node12/node_modules/:/opt/nodejs/node_modules:$LAMBDA_RUNTIME_DIR/node_modules).

• PYTHONPATH – (Python 2.7, 3.6, 3.8) The Python library path ($LAMBDA_RUNTIME_DIR).

• GEM_PATH – (Ruby) The Ruby library path ($LAMBDA_TASK_ROOT/vendor/bundle/ruby/2.5.0:/opt/ruby/gems/2.5.0).

• AWS_XRAY_CONTEXT_MISSING – For X-Ray tracing, Lambda sets this to LOG_ERROR to avoid throwing runtime errors from the X-Ray SDK.

• AWS_XRAY_DAEMON_ADDRESS – For X-Ray tracing, the IP address and port of the X-Ray daemon.

• AWS_LAMBDA_DOTNET_PREJIT – For the .NET 6 and .NET 7 runtimes, set this variable to enable or disable .NET specific runtime optimizations. Values include always, never, and provisioned-concurrency. For more information, see Configuring provisioned concurrency for a function.

• TZ – The environment's time zone (UTC). The execution environment uses NTP to synchronize the system clock.

The sample values shown reflect the latest runtimes. The presence of specific variables or their values can vary on earlier runtimes.

Example scenario for environment variables

You can use environment variables to customize function behavior in your test environment and production environment. For example, you can create two functions with the same code but different configurations. One function connects to a test database, and the other connects to a production database. In this situation, you use environment variables to pass the hostname and other connection details for the database to the function.

The following example shows how to define the database host and database name as environment variables.

If you want your test environment to generate more debug information than the production environment, you could set an environment variable to configure your test environment to use more verbose logging or more detailed tracing.