Lambda layers - AWS Lambda

Lambda layers

You use layers with functions that use .zip file archives for deployment. For a function 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 use Lambda layers to share code in your functions. A layer contains code libraries, a custom runtime, or other dependencies. Layers help to reduce your .zip archive deployment package size, because layers are not included in the deployment package.

A function can use up to five layers at a time. The total unzipped size of the function and all layers can't exceed the unzipped deployment package size limit of 250 MB. For more information, see Lambda quotas.

You can create your own layers, or use layers that AWS or an AWS customer has published. Layers support resource-based policies for granting layer usage permissions to specific AWS accounts, AWS Organizations, or all accounts.

You can also use the AWS Serverless Application Model (AWS SAM) to manage layers and your function's layer configuration. For instructions, see Working with layers in the AWS Serverless Application Model Developer Guide.

Create layers

When you create a new layer, Lambda creates the layer as version 1. You can configure permissions on an existing layer version, but to make any other changes, you must create a new version.

To create a layer (console)

  1. Open the Layers page of the Lambda console.

  2. Choose Create layer.

  3. 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, choose your .zip file, and then choose Open.

    • To upload a file from Amazon Simple Storage Service (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 a list of runtimes that are compatible with the layer. The list of runtimes is optional, but it makes the layer easier to discover.

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 the following output:

{ "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.

Manage layers

To find layers 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 the following output:

{ "Layers": [ { "LayerName": "my-layer", "LayerArn": "arn:aws:lambda:us-east-2:123456789012:layer:my-layer", "LatestMatchingVersion": { "LayerVersionArn": "arn:aws: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, you can omit the runtime option. The details in the response reflect the latest version of the layer. See all the versions of a layer with list-layer-versions. To see more information about a version, use get-layer-version.

aws lambda get-layer-version --layer-name my-layer --version-number 2

You should see the following output:

{ "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:2", "Description": "My layer", "CreatedDate": "2018-11-15T00:37:46.592+0000", "Version": 2, "CompatibleRuntimes": [ "python3.6", "python3.7", "python3.8" ] }

The link in the response lets you download the layer archive. The link is valid for 10 minutes.

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

Include library dependencies in a layer

Each Lambda runtime adds specific /opt directory folders to the PATH variable. If the layer uses the same folder structure, 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 AWS X-Ray SDK └ 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 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 Jackson jar file └ java/lib/jackson-core-2.2.3.jar

Example file structure for JQ library └ bin/jq

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

Layer permissions

To configure a Lambda function with a layer, you need permission to call GetLayerVersion on the layer version. For functions in your account, you can get this permission from your user policy.

To use a layer in another account, the owner of the other account must grant your account permission in a resource-based policy.

To grant layer-usage permission to another account, add a statement to the layer version's permissions policy with 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 the following output:

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 version of a layer. Repeat the process each time that you create a new layer version.

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

Configure a function to use layers

You can specify up to five layers in your Lambda function's configuration, during or after function creation. You choose a specific version of a layer to use. If you want to use a different version later, you can update your function's configuration.

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

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

You should see the following output:

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

You must specify the version of each layer to use by providing the full Amazon Resource Name (ARN) of the layer version. When you add layers to a function that already has layers, the new list overwrites the previous list. Include all layers every time that you update the layer configuration. To remove all layers, specify an empty list.

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

While your function is running, it can access the content of the layer in the /opt directory. Layers are applied in the order that's specified, merging any folders with the same name. If the same file appears in multiple layers, the version in the last applied layer is used.

The creator of a layer can delete the version of the layer that you're using. When this happens, 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.

Add an updated layer version to your function

Use the update-function-configuration command to add an updated layer version to your function.

The layers parameter for this command is a list of all of the layer versions to add to the function. If the function already has layers, the new list overwrites the previous list. If you want to update only one of the layer versions, the layers parameter needs to include the ARNs of the existing layer versions.

The following procedure assumes that you have packaged the updated layer code into a local file named

Add an updated layer version to your function

  1. (Optional) If the new layer version is not published yet, publish the new version.

    aws lambda publish-layer-version --layer-name my-layer --description "My layer" --license-info "MIT" \ --zip-file "fileb://" --compatible-runtimes python3.6 python3.7
  2. (Optional) If the function has more than one layer, get the current layer versions associated with the function.

    aws lambda get-function-config --function-name my-function --query 'Layers[*].Arn' --output yaml

    (Optional) You can also get the latest version of a layer based on the layer name.

    aws lambda list-layer-versions --layer-name my-layer --query 'LayerVersions[0].LayerVersionArn'
  3. Add the new layer version to the function. In the following example command, the function also has a layer version named other-layer:5.

    aws lambda update-function-configuration --function-name my-function \ --layers arn:aws:lambda:us-east-2:123456789012:layer:my-layer:2 \ arn:aws:lambda:us-east-2:123456789012:layer:other-layer:5

AWS CloudFormation and AWS SAM

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

Example blank-nodejs/template.yml – Serverless resources

AWSTemplateFormatVersion: '2010-09-09' Transform: 'AWS::Serverless-2016-10-31' Description: An AWS 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 AWS 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, AWS SAM creates a new version of the layer and updates the mapping.

Sample applications

The GitHub repository for this guide provides 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 AWS Lambda.