Creating layer content Compiling the .zip file archive for your layer Including library dependencies in a layer Language-specific instructions Creating a layer Deleting a layer version Configuring layer permissions Using AWS CloudFormation with layers

Creating and sharing Lambda layers

Lambda layers provide a convenient way to package libraries and other dependencies that you can use with your Lambda functions. Using layers reduces the size of uploaded deployment archives and makes it faster to deploy your code.

A layer is a .zip file archive that can contain additional code or data. A layer can contain libraries, a custom runtime, data, or configuration files. Layers 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 functions defined as a container image, you 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 AWS Compute Blog.

You can create layers using the Lambda console, the Lambda API, AWS CloudFormation, or the AWS Serverless Application Model (AWS SAM). For more information about creating layers with AWS SAM, see Working with layers in the AWS Serverless Application Model Developer Guide.

Note

For Node.js runtimes 16 and earlier, Lambda doesn't support ES module dependencies in layers. Lambda does support ES module dependencies for Node.js 18.

Sections

Creating layer content
Compiling the .zip file archive for your layer
Including library dependencies in a layer
Language-specific instructions
Creating a layer
Deleting a layer version
Configuring layer permissions
Using AWS CloudFormation with layers

Creating layer content

When you create a layer, you must bundle all its content into a .zip file archive. You upload the .zip file archive to your layer from Amazon Simple Storage Service (Amazon S3) or your local machine. Lambda extracts the layer contents into the /opt directory when setting up the execution environment for the function.

Compiling the .zip file archive for your layer

You build your layer code into a .zip file archive using the same procedure that you would use for a function deployment package. If your layer includes any native code libraries, you must compile and build these libraries using a Linux development machine so that the binaries are compatible with Amazon Linux.

When you create a layer, you can specify whether the layer is compatible with one or both of the instruction set architectures. You may need to set specific compile flags to build a layer that is compatible with the arm64 architecture.

One way to ensure that you package libraries correctly for Lambda is to use AWS Cloud9. For more information, see Using Lambda layers to simplify your development process on the AWS Compute Blog.

Including library dependencies in a layer

For each Lambda runtime, the PATH variable includes specific folders in the /opt directory. If you define the same folder structure in your layer .zip file archive, your function code can access the layer content without the need to specify the path.

The following table lists the folder paths that each runtime supports.

Layer paths for each Lambda runtime
Runtime	Path
Node.js	`nodejs/node_modules`
	`nodejs/node14/node_modules` (`NODE_PATH`)
	`nodejs/node16/node_modules` (`NODE_PATH`)
	`nodejs/node18/node_modules` (`NODE_PATH`)
Python	`python`
Python	`python/lib/python3.10/site-packages`(site directories)
Java	`java/lib` (`CLASSPATH`)
Ruby	`ruby/gems/2.7.0` (`GEM_PATH`)
Ruby	`ruby/lib` (`RUBYLIB`)
All runtimes	`bin` (`PATH`)
All runtimes	`lib` (`LD_LIBRARY_PATH`)

The following examples show how you can structure the folders in your layer .zip archive.

For more information about path settings in the Lambda execution environment, see Defined runtime environment variables.

Language-specific instructions

For language-specific instructions on how to create a .zip file archive, see the following topics.

Creating a layer

You can create new layers using the Lambda console or the Lambda API.

Layers can have one or more version. When you create a layer, Lambda sets the layer version to version 1. You can configure permissions on an existing layer version, but to update the code or make other configuration changes, you must create a new version of the layer.

To create a layer (console)

Open the Layers page of the Lambda console.
Choose Create layer.
Under Layer configuration, for Name, enter a name for your layer.
(Optional) For Description, enter a description for your layer.
To upload your layer code, do one of the following:
- To upload a .zip file from your computer, choose Upload a .zip file. Then, choose Upload to select your local .zip file.
- To upload a file from Amazon S3, choose Upload a file from Amazon S3. Then, for Amazon S3 link URL, enter a link to the file.
(Optional) For Compatible architectures, choose one value or both values.
(Optional) For Compatible runtimes, choose up to 15 runtimes.
(Optional) For License, enter any necessary license information.
Choose Create.

To create a layer (API)

To create a layer, use the publish-layer-version command with a name, description, .zip file archive, a list of runtimes and a list of architectures that are compatible with the layer. The runtimes and architecture parameters are optional.


aws lambda publish-layer-version --layer-name my-layer \
    --description "My layer" \
    --license-info "MIT" \
    --zip-file fileb://layer.zip \
    --compatible-runtimes python3.7 python3.8 \
    --compatible-architectures "arm64" "x86_64"

You should see output similar to the following:


{
    "Content": {
        "Location": "https://awslambda-us-east-2-layers.s3.us-east-2.amazonaws.com/snapshots/123456789012/my-layer-4aaa2fbb-ff77-4b0a-ad92-5b78a716a96a?versionId=27iWyA73cCAYqyH...",
        "CodeSha256": "tv9jJO+rPbXUUXuRKi7CwHzKtLDkDRJLB3cC3Z/ouXo=",
        "CodeSize": 169
    },
    "LayerArn": "arn:aws:lambda:us-east-2:123456789012:layer:my-layer",
    "LayerVersionArn": "arn:aws:lambda:us-east-2:123456789012:layer:my-layer:1",
    "Description": "My layer",
    "CreatedDate": "2018-11-14T23:03:52.894+0000",
    "Version": 1,
    "CompatibleArchitectures": [
        "arm64",
        "x86_64"
     ],
    "LicenseInfo": "MIT",
    "CompatibleRuntimes": [
        "python3.7",
        "python3.8"
    ]
}

Note

Each time that you call publish-layer-version, you create a new version of the layer.

Deleting a layer version

To delete a layer version, use the delete-layer-version command.


aws lambda delete-layer-version --layer-name my-layer --version-number 1

When you delete a layer version, you can no longer configure a Lambda function to use it. However, any function that already uses the version continues to have access to it. Version numbers are never reused for a layer name.

Configuring layer permissions

By default, a layer that you create is private to your AWS account. However, you can optionally share the layer with other accounts or make it public.

To grant layer-usage permission to another account, add a statement to the layer version's permissions policy using the add-layer-version-permission command. In each statement, you can grant permission to a single account, all accounts, or an organization.


aws lambda add-layer-version-permission --layer-name xray-sdk-nodejs --statement-id xaccount \
--action lambda:GetLayerVersion  --principal 111122223333 --version-number 1 --output text

You should see output similar to the following:


e210ffdc-e901-43b0-824b-5fcd0dd26d16    {"Sid":"xaccount","Effect":"Allow","Principal":{"AWS":"arn:aws:iam::111122223333:root"},"Action":"lambda:GetLayerVersion","Resource":"arn:aws:lambda:us-east-2:123456789012:layer:xray-sdk-nodejs:1"}

Permissions apply only to a single layer version. Repeat the process each time that you create a new layer version.

For more examples, see Granting layer access to other accounts.

Using AWS CloudFormation with layers

You can use AWS CloudFormation to create a layer and associate the layer with your Lambda function. The following example template creates a layer named blank-nodejs-lib and attaches the layer to the Lambda function using the Layers property.



AWSTemplateFormatVersion: '2010-09-09'
Transform: 'AWS::Serverless-2016-10-31'
Description: A Lambda application that calls the Lambda API.
Resources:
  function:
    Type: AWS::Serverless::Function
    Properties:
      Handler: index.handler
      Runtime: nodejs14.x
      CodeUri: function/.
      Description: Call the Lambda API
      Timeout: 10
      # Function's execution role
      Policies:
        - AWSLambdaBasicExecutionRole
        - AWSLambda_ReadOnlyAccess
        - AWSXrayWriteOnlyAccess
      Tracing: Active
      Layers:
        - !Ref libs
  libs:
    Type: AWS::Lambda::LayerVersion
    Properties:
      LayerName: blank-nodejs-lib
      Description: Dependencies for the blank sample app.
      Content:
        S3Bucket: my-bucket-region-123456789012
        S3Key: layer.zip
      CompatibleRuntimes:
        - nodejs14.x

Warning Javascript is disabled or is unavailable in your browser.

To use the Amazon Web Services Documentation, Javascript must be enabled. Please refer to your browser's Help pages for instructions.

Document Conventions

Private networking

Response streaming

Creating and sharing Lambda layers

Note

Sections

Creating layer content

Compiling the .zip file archive for your layer

Including library dependencies in a layer

Example file structure for the AWS X-Ray SDK for Node.js

Example file structure for the Pillow library

Example file structure for the JSON gem

Example file structure for the Jackson JAR file

Example file structure for the jq library

Language-specific instructions

Creating a layer

To create a layer (console)

Note

Deleting a layer version

Configuring layer permissions

Using AWS CloudFormation with layers