How do I resolve the "Unable to import module" error that I receive when I run Lambda code in Python?

Short description

You receive an "Unable to import module" error when the Lambda environment can't find the specified library in your Lambda deployment package.

To resolve this error, create a deployment package with all the required libraries. Or, create a Lambda layer with the required libraries, and attach the layer to your Lambda function. Then, reuse the layer across multiple Lambda functions.

Resolution

Create a Lambda layer to attach to multiple Lambda functions

Note: When you create the Lambda layer, put the libraries in the /python or python/lib/python3.x/site-packages folders. The deployment package size limit for direct upload is 50 MB zipped, and 250 MB unzipped. For more information, see Function configuration, deployment, and execution.

It's a best practice to create the Lambda layer on the same operating system (OS) that your Lambda runtime is based on. For example, Python 3.12 is based on an Amazon Linux 2023 Amazon Machine Image (AMI). So, create the layer on an Amazon Linux 2023 OS.

If you use an Amazon Elastic Compute Cloud (Amazon EC2) instance and have permission to use the PublishLayerVersion API call, then proceed to step 5. Or, if you use AWS CloudShell for authentication, then proceed to step 5.

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.

Complete the following steps:

1. Use CloudShell or the Amazon EC2 console to create an instance with Amazon Linux 2023 AMI.

2. Create an AWS Identity and Access Management (IAM) policy that grants permissions to call the PublishLayerVersion API operation.

Example IAM policy:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "VisualEditor0",
            "Effect": "Allow",
            "Action": "lambda:PublishLayerVersion",
            "Resource": "arn:aws:lambda:*:*:layer:*"
        }
    ]
}

3. Create an IAM role, and then attach the IAM policy to the role.

4. Attach the IAM role to the instance.

5. Connect to your instance or open CloudShell.

6. Run the following commands to create a new folder and use pip to install the library that's named numpy:

mkdir -p lambda-layer/python
cd lambda-layer/python
pip3 install --platform manylinux2014_x86_64 –target . --python-version 3.12 --only-binary=:all: numpy

Note: Update the platform parameter for your function type. For a x86_64 Lambda function, set the value to manylinux2014_x86_64. For an arm64 function, set the value to manylinux2014_aarch64. Update the python-version parameter to the same version that your Lambda function uses. You aren't required to install Python 3.12 because pip automatically downloads packages compatible with Python 3.12.

7. Run the following command to put the contents of the python folder into a layer.zip file:

cd ..
zip -r layer.zip python

8. To publish the Lambda layer, run the following publish-layer-version command:

aws lambda publish-layer-version --layer-name numpy-layer --zip-file fileb://layer.zip --compatible-runtimes python3.12 --region us-east-1

Note: Replace us-east-1 with the AWS Region of your Lambda function.

9. Add the layer to your Lambda function.

10. To test your Lambda function, import the package and print the version.

Example output:

import json
import numpy

def lambda_handler(event, context):
    print(numpy.__version__)
    return {
        'statusCode': 200,
        'body': json.dumps('Hello from Lambda!')
    }

Add multiple Python packages to the same layer

To bundle several libraries into one layer, install the libraries into the same folder before you zip the folder. Pass all package names to a single pip3 install command, or run pip multiple times with the same --target directory.

Complete the following steps:

1. Run the following commands to create the layer folder:

mkdir -p lambda-layer/python
cd lambda-layer/python

2. Install all the required libraries into the folder. Use one of the following methods:

Method A: List package names directly in the command

pip3 install --platform manylinux2014_x86_64 --target . --python-version 3.12 --only-binary=:all: requests pandas numpy

Method B: Use a requirements.txt file

A requirements.txt file is a plain text file that lists one Python package per line. Use this method when you have many packages or want to pin specific versions.

First, create a requirements.txt file with the packages that you want to install.

Example contents:

requests 
pandas==2.2.2
numpy>=1.26.0

Then, run the following command to install all packages listed in the file:

pip3 install --platform manylinux2014_x86_64 --target . --python-version 3.12 --only-binary=:all: -r requirements.txt

4. Complete steps 7-9 in the Create a Lambda layer to attach multiple Lambda functions section to zip the folder and publish the layer.

Note: Confirm that the unzipped layer is under 250 MB and the zipped layer is under 50 MB. If your packages exceed these limits, then split the packages across multiple layers. A Lambda function can have up to five layers attached.

Add a Python package to an existing layer

Lambda layer versions are immutable. To add a package to an existing layer, publish a new version of the layer that includes both the existing libraries and the new libraries. Then, point your Lambda function to the new layer version.

Complete the following steps:

1. Run the following commands to recreate the layer's python folder with the existing libraries and the new libraries:

mkdir -p lambda-layer/python
cd lambda-layer/python
pip3 install --platform manylinux2014_x86_64 --target . --python-version 3.12 --only-binary=:all: requests pandas numpy boto3

2. Run the following commands to zip the folder:

cd ..
zip -r layer.zip python

3. Run the following commands to publish a new version layer with same layer name as the preceding layer:

aws lambda publish-layer-version --layer-name my-layer --zip-file fileb://layer.zip --compatible-runtimes python3.12 --region us-east-1

Note: The output includes a new layer version Amazon Resource Name (ARN) with an incremented version number.

4. Run the following commands to update your Lambda function to use the new layer version:

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

Note: Replace the layer ARN with the layer version ARN from the preceding step.

Existing functions that reference the older layer version continue to work. Existing functions use the new packages only after you update the existing functions to the new version.

Related information

Working with .zip file archives for Python Lambda functions

Working with layers for Python Lambda functions

How do I install a Lambda compatible Python deployment package with compiled code on macOS or Windows OS?

How do I troubleshoot "permission denied" or "unable to import module" errors when I upload a Lambda deployment package?