How do I resolve Lambda deployment package size limit errors when my function or layer exceeds the maximum size that's allowed unzipped?

8 minute read

When I try to deploy or update my AWS Lambda function or layer, I receive an error message.

Short description

If your Lambda function code size and layers exceed 250 MB unzipped, then the deployment package fails deployment. If you then try to deploy or update your AWS Lambda function or layer, then you receive one of the following error messages:

"Unzipped size must be smaller than 262144000 bytes"

"Function code combined with layers exceeds the maximum allowed size of 262144000 bytes"

"RequestEntityTooLargeException"

"The deployment package of your Lambda function is too large to enable inline code editing"

To resolve this issue, take the following troubleshooting steps to manage your deployment package configuration.

Note: If you receive errors when you run AWS Command Line Interface (AWS CLI) commands, then see Troubleshooting errors for the AWS CLI. Also, make sure that you're using the most recent AWS CLI version.

Resolution

Check your deployment package and layer size

The Lambda layer file size limit is 50 MB zipped and 250 MB unzipped. Check whether the size quota issue is with your function code, your layers, or a combination of both.

To check your function's code size and attached layers, run the following get-function AWS CLI command:

aws lambda get-function --function-name my-function --query 'Configuration.[CodeSize, Layers]'

Note: Replace my-function with your function.

The preceding command output returns the zipped deployment package size in bytes and attached layers. For example, the output [5242880, null] shows a 5 MB zipped package with no layers attached.

Reduce your deployment package size

To reduce your deployment package size, remove unnecessary dependencies.

Review your requirements.txt or package.json files, and then remove unused libraries or modules. For Python, run the following command to install only the required packages:

pip install --target ./package -r requirements.txt

Exclude unnecessary files

Make sure that your deployment package doesn't include files that you don't require at runtime. For example, don't include test directories, .git/ folders, documentation, or IDE configuration files. Use your build process or packaging script to exclude these files before you create the .zip archive.

Use OS native compiled dependencies

Certain libraries include pre-compiled binaries for multiple platforms. Use operating system (OS) native compiled dependencies to build your package. For example, in an Amazon Linux 2023 compatible environment, run the following command to avoid unnecessary platform binaries:

docker run --rm -v $(pwd):/var/task public.ecr.aws/lambda/python:3.12 pip install -r requirements.txt -t /var/task/package

Use Lambda layers to manage shared dependencies

Move shared or large dependencies into a Lambda layer. The Lambda layer separates reusable libraries from your function code to share across multiple functions.

Complete the following steps:

To package your dependencies into a layer-compatible directory structure, run the following Python command:

mkdir -p python/lib/python3.12/site-packages
pip install -r requirements.txt -t python/lib/python3.12/site-packages
zip -r my-layer.zip python

Note: Replace my-layer with your layer.

To publish the layer, run the following publish-layer-version AWS CLI command:

aws lambda publish-layer-version \
--layer-name my-dependencies \
--zip-file fileb://my-layer.zip \
--compatible-runtimes python3.12

Note: Replace my-layer with your layer and my-dependencies with your dependencies.

To attach the layer to your function, run the following update-function-configuration AWS CLI command:

aws lambda update-function-configuration \
--function-name my-function \
--layers arn:aws:lambda:us-east-1:123456789012:layer:my-dependencies:1

Note: Replace my-function with your function and my-dependencies with your dependencies. A function supports up to 5 attached layers.

Use an Amazon S3 bucket for packages less than 250 MB

Use Amazon Simple Storage Service (Amazon S3) for large deployment packages. If your deployment package is larger than 50 MB zipped and less than 250 MB unzipped, then upload it to an Amazon S3 bucket. Make sure that the S3 bucket is in the same AWS Region as your function. The total unzipped size of the function and all layers can't exceed the unzipped deployment package size limit of 250 MB.

To use an Amazon S3 bucket for large deployment packages, complete the following steps:

Run the following cp command:

aws s3 cp my-function.zip s3://my-bucket/my-function.zip

Note: Replace my-function with your function amd my-function.zip with your deployment package.

To update the function code from S3, run the following update-function-code AWS CLI command:

aws lambda update-function-code \
--function-name my-function \
--s3-bucket my-bucket \
--s3-key my-function.zip

Note: Replace my-function with your function, my-bucket with your bucket, and my-function.zip with your deployment package.

Use container images for packages larger than 250 MB

If your deployment package is larger than 250 MB unzipped, then use a container image. Container images support up to 10 GB.

Note: Container image-based Lambda functions don't support layers. Make sure that you include all dependencies in your container image.

To use a container system, complete the following steps:

To use an AWS base image to create a Docker file for a multi-stage build, run the following script:

# Builder stage
FROM public.ecr.aws/lambda/python:3.12 as builder

# Install Python packages
RUN pip install --no-cache-dir -r requirements.txt --target "${LAMBDA_TASK_ROOT}"

# Final stage
FROM public.ecr.aws/lambda/python:3.12

# Copy installed packages from builder stage
COPY --from=builder ${LAMBDA_TASK_ROOT} ${LAMBDA_TASK_ROOT}

COPY app.py ${LAMBDA_TASK_ROOT}

CMD ["app.handler"]

To use an AWS base image to create a Docker file for a single-stage build, run the following script:

FROM public.ecr.aws/lambda/python:3.12

COPY requirements.txt ${LAMBDA_TASK_ROOT}
RUN pip install --no-cache-dir -r requirements.txt

COPY app.py ${LAMBDA_TASK_ROOT}

CMD ["app.handler"]

To build the image with the required platform specification for your architecture, run the following command:

docker buildx build --platform linux/amd64 --provenance=false -t my-function:latest .

Note: Replace my-function with your function.

To authenticate with Amazon Elastic Container Registry (Amazon ECR), run the following get-login-password AWS CLI command:

aws ecr get-login-password --region us-east-1 | docker login --username AWS --password-stdin 123456789012.dkr.ecr.us-east-1.amazonaws.com

To create a repository, run the following create-repository AWS CLI command:

aws ecr create-repository --repository-name my-function

Note: Replace my-function with your Lambda function name.

Tag the image:

docker tag my-function:latest 123456789012.dkr.ecr.us-east-1.amazonaws.com/my-function:latest

Note: Replace my-function with your function.

Push the image:

docker push 123456789012.dkr.ecr.us-east-1.amazonaws.com/my-function:latest

Note: Replace my-function with your function.

To create a function to use the container image, run the following create-function AWS CLI command:

aws lambda create-function \
--function-name my-function \
--package-type Image \
--code ImageUri=123456789012.dkr.ecr.us-east-1.amazonaws.com/my-function:latest \
--role arn:aws:iam::123456789012:role/my-lambda-role

Note: Replace my-function with your function and my-lambda-role with your Lambda role.

Resolve layer-specific size errors

If your layer exceeds size limits, then take the following actions:

Split large layers into multiple smaller layers and group dependencies logically.
Remove unused transitive dependencies from the layer.
Use architecture-specific builds arm64 or x86_64 to exclude binaries for these platforms.
Move the largest dependencies into a container image deployment.

For more information, see How do I use container images with Lambda?

Use Amazon EFS for large runtime dependencies

If your function needs access to large files or libraries at runtime, then use Amazon Elastic File System (Amazon EFS). To keep your deployment package small, mount an Amazon EFS file system to your Lambda function. EFS supports multiple storage classes for storage efficiency and is accessible from multiple functions.

Note: When you use EFS, you incur charges. For more information, see Amazon EFS Pricing.

To Use Amazon EFS for large runtime dependencies, complete the following steps:

Create an EFS file system in the same Amazon Virtual Private Cloud (Amazon VPC) as your Lambda function.
Note: Your function must run in a VPC to access EFS.
Create an EFS access point with valid Portable Operating System Interface (POSIX) permissions.
Configure your Lambda function to run in the VPC and mount the EFS file system at /mnt/efs or your preferred directory.
Upload your large dependencies or data files to the EFS file system. For example, use an Amazon Elastic Compute Cloud (Amazon EC2) instance or AWS DataSync.
Reference the EFS path in your function code when you load dependencies or data.

Note: Latency can increase the first time that you invoke your function because of the VPC network setup or cold start. For more information, see Managing mount targets.