Working with .zip file archives for Python Lambda Event Functions
Your AWS Lambda function’s code comprises a .py file containing your function’s handler code, together with any additional packages and modules your code depends on. To deploy this function code to Lambda, you use a deployment package. This package may either be a .zip file archive or a container image. For more information about using container images with Python, see Deploy Python Lambda Event Functions with container images.
To create your deployment package as .zip file archive, you can use your command-line tool’s built-in .zip file archive utility, or any other
.zip file utility such as 7zipzip tool in a Linux or MacOS environment. To use the same commands in Windows, you can
install the Windows Subsystem for Linux
Note that Lambda uses POSIX file permissions, so you may need to set permissions for the deployment package folder
Runtime dependencies in Python
For Lambda Event Functions that use the Python runtime, a dependency can be any Python package or module. When you deploy your function using a .zip archive, you can either add these dependencies to your .zip file with your function code or use a Lambda layer. A layer is a separate .zip file that can contain additional code and other content. To learn more about using Lambda layers in Python, see Working with layers for Python Lambda Event Functions.
The Lambda Python runtimes include the AWS SDK for Python (Boto3) and its dependencies. Lambda provides the SDK in the runtime for deployment scenarios where you are unable to add your own dependencies. These scenarios include creating functions in the console using the built-in code editor or using inline functions in AWS Serverless Application Model (AWS SAM) or CloudFormation templates.
Lambda periodically updates the libraries in the Python runtime to include the latest updates and security patches. If your function uses the version of the Boto3 SDK included in the runtime but your deployment package includes SDK dependencies, this can cause version misalignment issues. For example, your deployment package could include the SDK dependency urllib3. When Lambda updates the SDK in the runtime, compatibility issues between the new version of the runtime and the version of urllib3 in your deployment package can cause your function to fail.
Important
To maintain full control over your dependencies and to avoid possible version misalignment issues, we recommend you add all of your function's dependencies to your deployment package, even if versions of them are included in the Lambda runtime. This includes the Boto3 SDK.
To find out which version of the SDK for Python (Boto3) is included in the runtime you're using, see Runtime-included SDK versions.
Under the AWS shared responsibility model, you are responsible for the management of any dependencies in your functions' deployment packages. This includes applying updates and security patches. To update dependencies in your function's deployment package, first create a new .zip file and then upload it to Lambda. See Creating a .zip deployment package with dependencies and Creating and updating Python Lambda Event Functions using .zip files for more information.
Creating a .zip deployment package with no dependencies
If your function code has no dependencies, your .zip file contains only the .py file with your function's handler code. Use your preferred zip utility to create a .zip file with your .py file at the root. If the .py file is not at the root of your .zip file, Lambda won't be able to run your code.
To learn how to deploy your .zip file to create a new function or update an existing one, see Creating and updating Python Lambda Event Functions using .zip files.
Creating a .zip deployment package with dependencies
If your function code depends on additional packages or modules, you can either add these dependencies to your .zip file with your function code or use a Lambda layer. The instructions in this section show you how to include your dependencies in your .zip deployment package. For Lambda to run your code, the .py file containing your handler code and all of your function's dependencies must be installed at the root of the .zip file.
Suppose your function code is saved in a file named lambda_function.py. The following example CLI commands create a .zip file
named my_deployment_package.zip containing your function code and its dependencies. You can either install your dependencies directly
to a folder in your project directory or use a Python virtual environment.
To create the deployment package (project directory)
-
Navigate to the project directory containing your
lambda_function.pysource code file. In this example, the directory is namedmy_function.cd my_function -
Create a new directory named package into which you will install your dependencies.
mkdir packageNote that for a .zip deployment package, Lambda expects your source code and its dependencies all to be at the root of the .zip file. However, installing dependencies directly in your project directory can introduce a large number of new files and folders and make navigating around your IDE difficult. You create a separate
packagedirectory here to keep your dependencies separate from your source code. -
Install your dependencies in the
packagedirectory. The example below installs the Boto3 SDK from the Python Package Index using pip. If your function code uses Python packages you have created yourself, save them in thepackagedirectory.pip install --target ./package boto3 -
Create a .zip file with the installed libraries at the root.
cd package zip -r ../my_deployment_package.zip .This generates a
my_deployment_package.zipfile in your project directory. -
Add the lambda_function.py file to the root of the .zip file
cd .. zip my_deployment_package.zip lambda_function.pyYour .zip file should have a flat directory structure, with your function's handler code and all your dependency folders installed at the root as follows.
my_deployment_package.zip |- bin | |-jp.py |- boto3 | |-compat.py | |-data | |-docs ... |- lambda_function.pyIf the .py file containing your function's handler code is not at the root of your .zip file, Lambda cannot run your code.
To create the deployment package (virtual environment)
-
Create and activate a virtual environment in your project directory. In this example the project directory is named
my_function.~$cd my_function~/my_function$python3.14 -m venv my_virtual_env~/my_function$source ./my_virtual_env/bin/activate -
Install your required libraries using pip. The following example installs the Boto3 SDK
(my_virtual_env) ~/my_function$pip install boto3 -
Use
pip showto find the location in your virtual environment where pip has installed your dependencies.(my_virtual_env) ~/my_function$pip show <package_name>The folder in which pip installs your libraries might be named
site-packagesordist-packages. This folder might be located in either thelib/python3.xorlib64/python3.xdirectory (where python3.x represents the version of Python you are using). -
Deactivate the virtual environment
(my_virtual_env) ~/my_function$deactivate -
Navigate into the directory containing the dependencies you installed with pip and create a .zip file in your project directory with the installed dependencies at the root. In this example, pip has installed your dependencies in the
my_virtual_env/lib/python3.14/site-packagesdirectory.~/my_function$cd my_virtual_env/lib/python3.14/site-packages~/my_function/my_virtual_env/lib/python3.14/site-packages$zip -r ../../../../my_deployment_package.zip . -
Navigate to the root of your project directory where the .py file containing your handler code is located and add that file to the root of your .zip package. In this example, your function code file is named
lambda_function.py.~/my_function/my_virtual_env/lib/python3.14/site-packages$cd ../../../../~/my_function$zip my_deployment_package.zip lambda_function.py
Dependency search path and runtime-included libraries
When you use an import statement in your code, the Python runtime searches the directories in its search path until it finds the
module or package. By default, the first location the runtime searches is the directory into which your .zip deployment package is decompressed
and mounted (/var/task). If you include a version of a runtime-included library in your deployment package, your version takes precedence over the version that's included in the runtime. Dependencies in your deployment package also have precedence over dependencies in layers.
When you add a dependency to a layer, Lambda extracts this to
/opt/python/lib/python3.x/site-packages (where python3.x represents the version of the
runtime you're using) or /opt/python. In the search path, these directories have precedence over the
directories containing the runtime-included libraries and pip-installed libraries (/var/runtime and /var/lang/lib/python3.x/site-packages). Libraries in function layers therefore have precedence
over versions included in the runtime.
Note
In the Python 3.11 managed runtime and base image, the AWS SDK and its dependencies are installed in the /var/lang/lib/python3.11/site-packages directory.
You can see the full search path for your function by adding the following code snippet.
import sys search_path = sys.path print(search_path)
Note
Because dependencies in your deployment package or layers take precedence over runtime-included libraries, this can cause version misalignment problems if you include an SDK dependency such as urllib3 in your package without including the SDK as well. If you deploy your own version of a Boto3 dependency, you must also deploy Boto3 as a dependency in your deployment package. We recommend that you package all of your function's dependencies, even if versions of them are included in the runtime.
You can also add dependencies in a separate folder inside your .zip package. For example, you might add a version of the Boto3 SDK to a folder
in your .zip package called common. When your .zip package is decompressed and mounted, this folder is placed inside the
/var/task directory. To use a dependency from a folder in your .zip deployment package in your code, use an import from
statement. For example, to use a version of Boto3 from a folder named common in your .zip package, use the following statement.
from common import boto3
Using __pycache__ folders
We recommend that you don't include __pycache__ folders in your function's deployment package. Python bytecode that's compiled
on a build machine with a different architecture or operating system might not be compatible with the Lambda execution environment.
Creating .zip deployment packages with native libraries
If your function uses only pure Python packages and modules, you can use the pip install command to install your dependencies on
any local build machine and create your .zip file. Many popular Python libraries, including NumPy and Pandas, are not pure Python and contain code
written in C or C++. When you add libraries containing C/C++ code to your deployment package, you must build your package correctly to ensure that
it's compatible with the Lambda execution environment.
Most packages available on the Python Package Index (PyPI
Some packages may only be available as source distributions. For these packages, you need to compile and build the C/C++ components yourself.
To see what distributions are available for your required package, do the following:
-
Search for the name of the package on the Python Package Index main page
. -
Choose the version of the package you want to use.
-
Choose Download files.
Working with built distributions (wheels)
To download a wheel that's compatible with Lambda, you use the pip --platform option. The platform tag you specify depends
on the operating system that your function's runtime is built on:
-
Python 3.12 and later runtimes are built on Amazon Linux 2023, which includes glibc 2.34. For these runtimes, use the
manylinux_2_28platform tags (manylinux_2_28_x86_64for x86_64 andmanylinux_2_28_aarch64for arm64). These wheels require a minimum glibc version of 2.28, which is compatible with Amazon Linux 2023. -
Python 3.11 and earlier runtimes are built on Amazon Linux 2, which includes glibc 2.26. For these runtimes, use the
manylinux2014platform tags (manylinux2014_x86_64for x86_64 andmanylinux2014_aarch64for arm64). These wheels require a minimum glibc version of 2.17, which is compatible with Amazon Linux 2.
Note
Many Python packages have stopped publishing manylinux2014 wheels in favor of manylinux_2_28. If you use a
Python 3.12 or later runtime, use the manylinux_2_28 platform tags to install the latest versions of these packages.
The following commands are for Python 3.12 and later runtimes. Replace with the version
of the Python runtime you are using.
3.x
If your function uses the x86_64 instruction set architecture, run the following
pip install command to install a compatible wheel in your package directory.
pip install \ --platform manylinux_2_28_x86_64 \ --target=package \ --implementation cp \ --python-version3.x\ --only-binary=:all: --upgrade \ <package_name>
If your function uses the arm64 instruction set architecture, run the following command.
pip install \ --platform manylinux_2_28_aarch64 \ --target=package \ --implementation cp \ --python-version3.x\ --only-binary=:all: --upgrade \ <package_name>
Working with source distributions
If your package is only available as a source distribution, you need to build the C/C++ libraries yourself. To make your package compatible with the Lambda execution environment, you need to build it in an environment that uses the same Amazon Linux operating system. You can do this by building your package in an Amazon Elastic Compute Cloud (Amazon EC2) Linux instance.
To learn how to launch and connect to an Amazon EC2 Linux instance, see Get started with Amazon EC2 in the Amazon EC2 User Guide.
Creating and updating Python Lambda Event Functions using .zip files
After you have created your .zip deployment package, you can use it to create a new Lambda function or update an existing one. You can deploy your .zip package using the Lambda console, the AWS Command Line Interface, and the Lambda API. You can also create and update Lambda functions using AWS Serverless Application Model (AWS SAM) and CloudFormation.
The maximum size for a .zip deployment package for Lambda is 250 MB (unzipped). Note that this limit applies to the combined size of all the files you upload, including any Lambda layers.
The Lambda runtime needs permission to read the files in your deployment package. In Linux permissions octal notation, Lambda needs 644 permissions for non-executable files (rw-r--r--) and 755 permissions (rwxr-xr-x) for directories and executable files.
In Linux and MacOS, use the chmod command to change file permissions on files and directories in your deployment package. For
example, to give a non-executable file the correct permissions, run the following command.
chmod 644 <filepath>
To change file permissions in Windows, see Set, View, Change, or Remove Permissions on an Object
Note
If you don't grant Lambda the permissions it needs to access directories in your deployment package, Lambda sets the permissions for those directories to 755 (rwxr-xr-x).
Creating and updating functions with .zip files using the console
To create a new function, you must first create the function in the console, then upload your .zip archive. To update an existing function, open the page for your function, then follow the same procedure to add your updated .zip file.
If your .zip file is less than 50MB, you can create or update a function by uploading the file directly from your local machine. For .zip files greater than 50MB, you must upload your package to an Amazon S3 bucket first. For instructions on how to upload a file to an Amazon S3 bucket using the AWS Management Console, see Getting started with Amazon S3. To upload files using the AWS CLI, see Move objects in the AWS CLI User Guide.
Note
You cannot change the deployment package type (.zip or container image) for an existing function. For example, you cannot convert a container image function to use a .zip file archive. You must create a new function.
To create a new function (console)
-
Open the Event Functions page
of the Lambda console and choose Create Event Function. -
Choose Author from scratch.
-
Under Basic information, do the following:
-
For Function name, enter the name for your function.
-
For Runtime, select the runtime you want to use.
-
(Optional) For Architecture, choose the instruction set architecture for your function. The default architecture is x86_64. Ensure that the .zip deployment package for your function is compatible with the instruction set architecture you select.
-
-
(Optional) Under Permissions, expand Change default execution role. You can create a new Execution role or use an existing one.
-
Choose Create Event Function. Lambda creates a basic 'Hello world' function using your chosen runtime.
To upload a .zip archive from your local machine (console)
-
In the Event Functions page
of the Lambda console, choose the function you want to upload the .zip file for. -
Select the Code tab.
-
In the Code source pane, choose Upload from.
-
Choose .zip file.
-
To upload the .zip file, do the following:
-
Select Upload, then select your .zip file in the file chooser.
-
Choose Open.
-
Choose Save.
-
To upload a .zip archive from an Amazon S3 bucket (console)
-
In the Event Functions page
of the Lambda console, choose the function you want to upload a new .zip file for. -
Select the Code tab.