Creating and sharing Lambda layers - AWS Lambda

Creating and sharing Lambda layers

A Lambda 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.

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.

Using the AWS CLI

You can create and upload a .zip file for your layer using the Lambda console or the AWS Command Line Interface (AWS CLI). For language-specific instructions, see the following topics.

Compiling the .zip file archive for your layer

You build your layer code into a .zip file archive using the same procedure as you would for a function. 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.

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



nodejs/node14/node_modules (NODE_PATH)



python/lib/python3.8/site-packages(site directories)


java/lib (CLASSPATH)


ruby/gems/2.5.0 (GEM_PATH)

ruby/lib (RUBYLIB)

All runtimes

bin (PATH)


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


Example file structure for the AWS X-Ray SDK for Node.js └ nodejs/node_modules/aws-xray-sdk

Example file structure for the Pillow library │ python/PIL └ python/Pillow-5.3.0.dist-info

Example file structure for the JSON gem └ ruby/gems/2.5.0/ | build_info | cache | doc | extensions | gems | └ json-2.1.0 └ specifications └ json-2.1.0.gemspec

Example file structure for the Jackson JAR file └ java/lib/jackson-core-2.2.3.jar

Example file structure for the jq library └ bin/jq

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

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)

  1. Open the Layers page of the Lambda console.

  2. Choose Create layer.

  3. Under Layer configuration, for Name, enter a name for your layer.

  4. (Optional) For Description, enter a description for your layer.

  5. 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.

  6. (Optional) For Compatible runtimes, choose up to 15 runtimes.

  7. (Optional) For License, enter any necessary license information.

  8. Choose Create.

To create a layer (API)

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

aws lambda publish-layer-version --layer-name my-layer --description "My layer" \ --license-info "MIT" --content S3Bucket=lambda-layers-us-east-2-123456789012, \ --compatible-runtimes python3.6 python3.7 python3.8

You should see output similar to the following:

{ "Content": { "Location": "", "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, "LicenseInfo": "MIT", "CompatibleRuntimes": [ "python3.6", "python3.7", "python3.8" ] }

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 210987654321 --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::210987654321: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: nodejs12.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::Serverless::LayerVersion Properties: LayerName: blank-nodejs-lib Description: Dependencies for the blank sample app. ContentUri: lib/. CompatibleRuntimes: - nodejs12.x