Using layers with your Lambda function

A Lambda layer is a .zip file archive that can contain additional code or other content. A layer can contain libraries, a custom runtime, data, or configuration files. Use layers to reduce deployment package size and to promote code sharing and separation of responsibilities so that you can iterate faster on writing business logic.

You can use layers only with Lambda functions deployed as a .zip file archive. For a function defined as a container image, you can package your preferred runtime and all code dependencies when you create the container image. For more information, see Working with Lambda layers and extensions in container images on the Amazon Compute Blog.

Prerequisites

Before you can configure a Lambda fuction to use a layer, you must:

Configuring functions to use layers

You can add up to five layers to a Lambda function. The total unzipped size of the function and all layers cannot exceed the unzipped deployment package size quota of 250 MB. For more information, see Lambda quotas.

If your functions consume a layer that a different Amazon account publishes, your functions can continue to use the layer version after it has been deleted, or after your permission to access the layer is revoked. However, you cannot create a new function that uses a deleted layer version.

Configuring layers with the console

The order in which you add the layers is the order in which Lambda later merges the layer content into the execution environment. You can change the layer merge order using the console.

Layers are versioned, and the content of each layer version is immutable. The layer owner can release a new layer version to provide updated content. You can use the console to update your functions' layer versions.

You cannot update functions' layer versions across Amazon accounts.

Configuring layers with the API

To add layers to your function, use the update-function-configuration command. The following example adds two layers: one from the same Amazon account as the function, and one from a different account.

aws lambda update-function-configuration --function-name my-function \
--layers arn:aws-cn:lambda:us-east-2:123456789012:layer:my-layer:3 \
arn:aws-cn:lambda:us-east-2:111122223333:layer:their-layer:2

You should see output similar to the following:

{
    "FunctionName": "test-layers",
    "FunctionArn": "arn:aws-cn:lambda:us-east-2:123456789012:function:my-function",
    "Runtime": "nodejs18.x",
    "Role": "arn:aws-cn:iam::123456789012:role/service-role/lambda-role",
    "Layers": [
        {
            "Arn": "arn:aws-cn:lambda:us-east-2:123456789012:layer:my-layer:3",
            "CodeSize": 169
        },
        {
            "Arn": "arn:aws-cn:lambda:us-east-2:111122223333:layer:their-layer:2",
            "CodeSize": 169
        }
    ],
    "RevisionId": "81cc64f5-5772-449a-b63e-12330476bcc4",
    ...
}

To specify the layer versions to use, you must provide the full Amazon Resource Name (ARN) of each layer version. When you add layers to a function that already has layers, you overwrite the previous list of layers. Be sure to include all layers every time that you update the layer configuration. The order in which you add the layers is the order in which Lambda later extracts the layer content into the execution environment.

To remove all layers, specify an empty list.

aws lambda update-function-configuration --function-name my-function --layers []

The creator of a layer can delete a version of the layer. If you're using that layer version in a function, your function continues to run as though the layer version still exists. However, when you update the layer configuration, you must remove the reference to the deleted version.

Layers are versioned, and the content of each layer version is immutable. The layer owner can release a new layer version to provide updated content. You can use the API to update the layer versions that your function uses.

Accessing layer content from your function

If your Lambda function includes layers, Lambda extracts the layer contents into the /opt directory in the function execution environment. Lambda extracts the layers in the order (low to high) listed by the function. Lambda merges folders with the same name, so if the same file appears in multiple layers, the function uses the version in the last extracted layer.

Each Lambda runtime adds specific /opt directory folders to the PATH variable. Your function code can access the layer content without the need to specify the path. For more information about path settings in the Lambda execution environment, see Defined runtime environment variables.

Refer to the layer paths for library dependencies to learn where to locate your libraries when creating a layer.

Finding layer information

To find layers in your Amazon account that are compatible with your Lambda function's runtime, use the list-layers command.

aws lambda list-layers --compatible-runtime python3.8

You should see output similar to the following:

{
    "Layers": [
        {
            "LayerName": "my-layer",
            "LayerArn": "arn:aws-cn:lambda:us-east-2:123456789012:layer:my-layer",
            "LatestMatchingVersion": {
                "LayerVersionArn": "arn:aws-cn:lambda:us-east-2:123456789012:layer:my-layer:2",
                "Version": 2,
                "Description": "My layer",
                "CreatedDate": "2018-11-15T00:37:46.592+0000",
                "CompatibleRuntimes": [
                    "python3.6",
                    "python3.7",
                    "python3.8",
                ]
            }
        }
    ]
}

To list all layers in your account, you can omit the --compatible-runtime option. The details in the response reflect the latest version of the layer.

You can also get the latest version of a layer using the list-layer-versions command.

aws lambda list-layer-versions --layer-name my-layer --query 'LayerVersions[0].LayerVersionArn

Using Amazon SAM to add a layer to a function

To automate the creation and mapping of layers in your application, use the Amazon Serverless Application Model (Amazon SAM). The AWS::Serverless::LayerVersion resource type creates a layer version that you can reference from your Lambda function configuration.

AWSTemplateFormatVersion: '2010-09-09'
Transform: 'AWS::Serverless-2016-10-31'
Description: An Amazon Lambda application that calls the Lambda API.
Resources:
  function:
    Type: AWS::Serverless::Function
    Properties:
      Handler: index.handler
      Runtime: nodejs12.x
      CodeUri: function/.
      Description: Call the Amazon Lambda API
      Timeout: 10
      # Function's execution role
      Policies:
        - AWSLambdaBasicExecutionRole
        - AWSLambda_ReadOnlyAccess
        - AWSXrayWriteOnlyAccess
      Tracing: Active
      Layers:
        - !Ref libs
  libs:
    Type: AWS::Serverless::LayerVersion
    Properties:
      LayerName: blank-nodejs-lib
      Description: Dependencies for the blank sample app.
      ContentUri: lib/.
      CompatibleRuntimes:
        - nodejs12.x

When you update your dependencies and deploy, Amazon SAM creates a new version of the layer and updates the mapping.

Sample applications

The GitHub repository for this guide provides blank sample applications that demonstrate the use of layers for dependency management.

For more information about the blank sample app, see Blank function sample application for Amazon Lambda. For other samples, see Lambda sample applications.