# Managing Lambda dependencies with layers A Lambda layer is a .zip file archive that contains supplementary code or data. Layers usually contain library dependencies, a [custom runtime](runtimes-custom.md), or configuration files. There are multiple reasons why you might consider using layers: + **To reduce the size of your deployment packages.** Instead of including all of your function dependencies along with your function code in your deployment package, put them in a layer. This keeps deployment packages small and organized. + **To separate core function logic from dependencies.** With layers, you can update your function dependencies independent of your function code, and vice versa. This promotes separation of concerns and helps you focus on your function logic. + **To share dependencies across multiple functions.** After you create a layer, you can apply it to any number of functions in your account. Without layers, you need to include the same dependencies in each individual deployment package. + **To use the Lambda console code editor.** The code editor is a useful tool for testing minor function code updates quickly. However, you can’t use the editor if your deployment package size is too large. Using layers reduces your package size and can unlock usage of the code editor. + **To lock an embedded SDK version.**The embedded SDKs may change without notice as AWS releases new services and features. You can lock a version of the SDK by [creating a Lambda layer](#chapter-layers) with the specific version needed. The function then always uses the version in the layer, even if the version embedded in the service changes. If you're working with Lambda functions in Go or Rust, we recommend against using layers. For Go and Rust functions, you provide your function code as an executable, which includes your compiled function code along with all of its dependencies. Putting your dependencies in a layer forces your function to manually load additional assemblies during the initialization phase, which can increase cold start times. For optimal performance for Go and Rust functions, include your dependencies along with your deployment package. The following diagram illustrates the high-level architectural differences between two functions that share dependencies. One uses Lambda layers, and the other does not. ![\[\]](http://docs.aws.amazon.com/lambda/latest/dg/images/lambda-layers-diagram.png) When you add a layer to a function, Lambda extracts the layer contents into the `/opt` directory in your function’s [execution environment](lambda-runtime-environment.md). All natively supported Lambda runtimes include paths to specific directories within the `/opt` directory. This gives your function access to your layer content. For more information about these specific paths and how to properly package your layers, see [Packaging your layer content](packaging-layers.md). You can include up to five layers per function. Also, you can use layers only with Lambda functions [deployed as a .zip file archive](configuration-function-zip.md). For functions [defined as a container image](images-create.md), 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](https://aws.amazon.com/blogs/compute/working-with-lambda-layers-and-extensions-in-container-images/) on the AWS Compute Blog. **Topics** + [ ## How to use layers ](#lambda-layers-overview) + [ ## Layers and layer versions ](#lambda-layer-versions) + [ # Packaging your layer content ](packaging-layers.md) + [ # Creating and deleting layers in Lambda ](creating-deleting-layers.md) + [ # Adding layers to functions ](adding-layers.md) + [ # Using AWS CloudFormation with layers ](layers-cfn.md) + [ # Using AWS SAM with layers ](layers-sam.md) ## How to use layers To create a layer, package your dependencies into a .zip file, similar to how you [create a normal deployment package](configuration-function-zip.md). More specifically, the general process of creating and using layers involves these three steps: + **First, package your layer content.** This means creating a .zip file archive. For more information, see [Packaging your layer content](packaging-layers.md). + **Next, create the layer in Lambda.** For more information, see [Creating and deleting layers in Lambda](creating-deleting-layers.md). + **Add the layer to your function(s).** For more information, see [Adding layers to functions](adding-layers.md). ## Layers and layer versions A layer version is an immutable snapshot of a specific version of a layer. When you create a new layer, Lambda creates a new layer version with a version number of 1. Each time you publish an update to the layer, Lambda increments the version number and creates a new layer version. Every layer version is identified by a unique Amazon Resource Name (ARN). When adding a layer to the function, you must specify the exact layer version you want to use (for example, `arn:aws:lambda:us-east-1:123456789012:layer:my-layer:1`). # Packaging your layer content A Lambda layer is a .zip file archive that contains supplementary code or data. Layers usually contain library dependencies, a [custom runtime](runtimes-custom.md), or configuration files. This section explains how to properly package your layer content. For more conceptual information about layers and why you might consider using them, see [Managing Lambda dependencies with layers](chapter-layers.md). The first step to creating a layer is to bundle all of your layer content into a .zip file archive. Because Lambda functions run on [Amazon Linux](https://docs.aws.amazon.com/linux/al2023/ug/what-is-amazon-linux.html), your layer content must be able to compile and build in a Linux environment. To ensure that your layer content works properly in a Linux environment, we recommend creating your layer content using a tool like [Docker](https://docs.docker.com/get-docker). **Topics** + [ ## Layer paths for each Lambda runtime ](#packaging-layers-paths) ## Layer paths for each Lambda runtime When you add a layer to a function, Lambda loads the layer content into the `/opt` directory of that execution environment. For each Lambda runtime, the `PATH` variable already includes specific folder paths within the `/opt` directory. To ensure that Lambda picks up your layer content, your layer .zip file should have its dependencies in one of the following folder paths: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/lambda/latest/dg/packaging-layers.html) The following examples show how you can structure the folders in your layer .zip archive. ------ #### [ Node.js ] **Example file structure for the AWS X-Ray SDK for Node.js** ``` xray-sdk.zip └ nodejs/node_modules/aws-xray-sdk ``` ------ #### [ Python ] **Example** ``` python/ # Required top-level directory └── requests/ └── boto3/ └── numpy/ └── (dependencies of the other packages) ``` ------ #### [ Ruby ] **Example file structure for the JSON gem** ``` json.zip └ ruby/gems/3.4.0/ | build_info | cache | doc | extensions | gems | └ json-2.1.0 └ specifications └ json-2.1.0.gemspec ``` ------ #### [ Java ] **Example file structure for the Jackson JAR file** ``` layer_content.zip └ java └ lib └ jackson-core-2.17.0.jar └ └ ... ``` ------ #### [ All ] **Example file structure for the jq library** ``` jq.zip └ bin/jq ``` ------ For language-specific instructions on packaging, creating, and adding a layer, refer to the following pages: + **Node.js** – [Working with layers for Node.js Lambda functions](nodejs-layers.md) + **Python** – [Working with layers for Python Lambda functions](python-layers.md) + **Ruby** – [Working with layers for Ruby Lambda functions](ruby-layers.md) + **Java** – [Working with layers for Java Lambda functions](java-layers.md) We recommend **against** using layers to manage dependencies for Lambda functions written in Go and Rust. This is because Lambda functions written in these languages compile into a single executable, which you provide to Lambda when you deploy your function. This executable contains your compiled function code, along with all of its dependencies. Using layers not only complicates this process, but also leads to increased cold start times because your functions need to manually load extra assemblies into memory during the init phase. To use external dependencies with Go and Rust Lambda functions, include them directly in your deployment package. # Creating and deleting layers in Lambda A Lambda layer is a .zip file archive that contains supplementary code or data. Layers usually contain library dependencies, a [custom runtime](runtimes-custom.md), or configuration files. This section explains how to create and delete layers in Lambda. For more conceptual information about layers and why you might consider using them, see [Managing Lambda dependencies with layers](chapter-layers.md). After you’ve [packaged your layer content](packaging-layers.md), the next step is to create the layer in Lambda. This section demonstrates how to create and delete layers using the Lambda console or the Lambda API only. To create a layer using AWS CloudFormation, see [Using AWS CloudFormation with layers](layers-cfn.md). To create a layer using the AWS Serverless Application Model (AWS SAM), see [Using AWS SAM with layers](layers-sam.md). **Topics** + [ ## Creating a layer ](#layers-create) + [ ## Deleting a layer version ](#layers-delete) ## Creating a layer To create a layer, you can either upload the .zip file archive from your local machine or from Amazon Simple Storage Service (Amazon S3). Lambda extracts the layer contents into the `/opt` directory when setting up the execution environment for the function. Layers can have one or more [layer versions](chapter-layers.md#lambda-layer-versions). When you create a layer, Lambda sets the layer version to version 1. You can change the permissions on an existing layer version at any time. However, 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](https://console.aws.amazon.com/lambda/home#/layers) of the Lambda console. 1. Choose **Create layer**. 1. Under **Layer configuration**, for **Name**, enter a name for your layer. 1. (Optional) For **Description**, enter a description for your layer. 1. 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. 1. (Optional) For **Compatible architectures**, choose one value or both values. For more information, see [Selecting and configuring an instruction set architecture for your Lambda function](foundation-arch.md). 1. (Optional) For **Compatible runtimes**, choose the runtimes that your layer is compatible with. 1. (Optional) For **License**, enter any necessary license information. 1. Choose **Create**. Alternatively, you can run the [publish-layer-version](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/lambda/publish-layer-version.html) AWS Command Line Interface (CLI) command. Example: ``` aws lambda publish-layer-version --layer-name my-layer --zip-file fileb://layer.zip --compatible-runtimes python3.14 ``` Each time that you run `publish-layer-version`, Lambda creates a new [version of the layer](chapter-layers.md#lambda-layer-versions). ## Deleting a layer version To delete a layer version, use the [DeleteLayerVersion](https://docs.aws.amazon.com/lambda/latest/api/API_DeleteLayerVersion.html) API operation. For example, run the [delete-layer-version](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/lambda/delete-layer-version.html) AWS CLI command with the layer name and layer version specified. ``` 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. Also, Lambda never reuses version numbers for a layer name. When calculating [quotas](gettingstarted-limits.md), deleting a layer version means it's no longer counted as part of the default 75 GB quota for storage of functions and layers. However, for functions that consume a deleted layer version, the layer content still counts towards the function's deployment package size quota (i.e. 250MB for .zip file archives). # Adding layers to functions A Lambda layer is a .zip file archive that contains supplementary code or data. Layers usually contain library dependencies, a [custom runtime](runtimes-custom.md), or configuration files. This section explains how to add a layer to a Lambda function. For more conceptual information about layers and why you might consider using them, see [Managing Lambda dependencies with layers](chapter-layers.md). Before you can configure a Lambda function to use a layer, you must: + [Package your layer content](packaging-layers.md) + [Create a layer in Lambda](creating-deleting-layers.md) + Make sure that you have permission to call the [GetLayerVersion](https://docs.aws.amazon.com/lambda/latest/api/API_GetLayerVersion.html) API on the layer version. For functions in your AWS account, you must have this permission in your [user policy](access-control-identity-based.md). To use a layer in another account, the owner of that account must grant your account permission in a [resource-based policy](access-control-resource-based.md). For examples, see [Granting Lambda layer access to other accounts](permissions-layer-cross-account.md). 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](gettingstarted-limits.md). Your functions can continue to use any layer version that you’ve already added, even after that layer version 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. **To add a layer to a function** 1. Open the [Functions page](https://console.aws.amazon.com/lambda/home#/functions) of the Lambda console. 1. Choose the function. 1. Scroll down to the **Layers** section, and then choose **Add a layer**. 1. Under **Choose a layer**, choose a layer source: 1. **AWS layers**: Choose from the list of [AWS-managed extensions](extensions-api-partners.md#aws-managed-extensions). 1. **Custom layers**: Choose a layer created in your AWS account. 1. **Specify an ARN**: To use a layer [from a different AWS account](permissions-layer-cross-account.md), such as a [third-party extension](extensions-api-partners.md), enter the Amazon Resource Name (ARN). 1. Choose **Add**. The order in which you add the layers is the order in which Lambda merges the layer content into the execution environment. You can change the layer merge order using the console. **To update layer merge order for your function (console)** 1. Open the [Functions page](https://console.aws.amazon.com/lambda/home#/functions) of the Lambda console. 1. Choose the function to configure. 1. Under **Layers**, choose **Edit** 1. Choose one of the layers. 1. Choose **Merge earlier** or **Merge later** to adjust the order of the layers. 1. Choose **Save**. Layers are versioned. The content of each layer version is immutable. The owner of a layer can release new layer versions to provide updated content. You can use the console to update the layer version attached to your functions. **To update layer versions for your function (console)** 1. Open the [Layers page](https://console.aws.amazon.com/lambda/home#/layers) of the Lambda console. 1. Choose the layer you want to update the version for. 1. Choose the **Functions using this version** tab. 1. Choose the functions you want to modify, then choose **Edit**. 1. For **Layer version**, choose the layer version to change to. 1. Choose **Update functions**. You cannot update function layer versions across AWS accounts. ## Finding layer information To find layers in your account that are compatible with your function’s runtime, use the [ListLayers](https://docs.aws.amazon.com/lambda/latest/api/API_ListLayers.html) API. For example, you can use the following [list-layers](https://docs.aws.amazon.com/cli/latest/reference/lambda/list-layers.html) AWS Command Line Interface (CLI) command: ``` aws lambda list-layers --compatible-runtime python3.14 ``` You should see output similar to the following: ``` { "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": "2025-04-15T00:37:46.592+0000", "CompatibleRuntimes": [ "python3.14" ] } } ] } ``` To list all layers in your account, omit the `--compatible-runtime` option. The response details show the latest version of each layer. You can also get the latest version of a layer using the [ListLayerVersions](https://docs.aws.amazon.com/lambda/latest/api/API_ListLayerVersions.html) API. For example, you can use the following `list-layer-versions` CLI command: ``` aws lambda list-layer-versions --layer-name my-layer ``` You should see output similar to the following: ``` { "LayerVersions": [ { "LayerVersionArn": "arn:aws:lambda:us-east-2:123456789012:layer:my-layer:2", "Version": 2, "Description": "My layer", "CreatedDate": "2023-11-15T00:37:46.592+0000", "CompatibleRuntimes": [ "java11" ] }, { "LayerVersionArn": "arn:aws:lambda:us-east-2:123456789012:layer:my-layer:1", "Version": 1, "Description": "My layer", "CreatedDate": "2023-11-15T00:27:46.592+0000", "CompatibleRuntimes": [ "java11" ] } ] } ``` # Using AWS CloudFormation with layers You can use CloudFormation to create a layer and associate the layer with your Lambda function. The following example template creates a layer named `my-lambda-layer` and attaches the layer to the Lambda function using the **Layers** property. In this example, the template specifies the Amazon Resource Name (ARN) of an existing IAM [execution role](lambda-intro-execution-role.md). You can also create a new execution role in the template using the CloudFormation [AWS::IAM::Role](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-iam-role.html) resource. Your function doesn't need any special permissions to use layers. ``` --- Description: CloudFormation Template for Lambda Function with Lambda Layer Resources: MyLambdaLayer: Type: AWS::Lambda::LayerVersion Properties: LayerName: my-lambda-layer Description: My Lambda Layer Content: S3Bucket: amzn-s3-demo-bucket S3Key: my-layer.zip CompatibleRuntimes: - python3.9 - python3.10 - python3.11 MyLambdaFunction: Type: AWS::Lambda::Function Properties: FunctionName: my-lambda-function Runtime: python3.9 Handler: index.handler Timeout: 10 Role: arn:aws:iam::111122223333:role/my_lambda_role Layers: - !Ref MyLambdaLayer ``` # Using AWS SAM with layers You can use the AWS Serverless Application Model (AWS SAM) to automate the creation of layers in your application. 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: AWS SAM Template for Lambda Function with Lambda Layer Resources: MyLambdaLayer: Type: AWS::Serverless::LayerVersion Properties: LayerName: my-lambda-layer Description: My Lambda Layer ContentUri: s3://amzn-s3-demo-bucket/my-layer.zip CompatibleRuntimes: - python3.9 - python3.10 - python3.11 MyLambdaFunction: Type: AWS::Serverless::Function Properties: FunctionName: MyLambdaFunction Runtime: python3.9 Handler: app.handler CodeUri: s3://amzn-s3-demo-bucket/my-function Layers: - !Ref MyLambdaLayer ```