Install & Compatibility
Where this runs
tested against v1.66.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.058s · 19MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 2.0s · import 0.052s · 19MB
20MB installed
● package 20MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
LambdaBuilder
✓ from aws_lambda_builders.builder import LambdaBuilder
This is the primary class for programmatically initiating a Lambda build process.
PythonPipWorkflow
✓ from aws_lambda_builders.workflows.python_pip.workflow import PythonPipWorkflow
Import a specific workflow class if you're directly invoking a workflow, though LambdaBuilder typically abstracts this.
BuildError
✓ from aws_lambda_builders.exceptions import BuildError
Common exception for handling build failures.
This example demonstrates how to programmatically use `aws-lambda-builders` to package a simple Python Lambda function with a dependency. It creates a dummy source directory, defines build parameters like runtime and output directories, then invokes the `LambdaBuilder` to create the deployment package. The output will be a zip-ready artifact in the specified `artifacts_dir`.
import os
from aws_lambda_builders.builder import LambdaBuilder
from aws_lambda_builders.exceptions import BuildError
# Create a dummy source directory with a requirements.txt and app.py
# In a real scenario, this would be your Lambda function's source code.
source_dir = './my_lambda_app_source'
artifacts_dir = './my_lambda_app_build'
os.makedirs(source_dir, exist_ok=True)
os.makedirs(artifacts_dir, exist_ok=True)
with open(os.path.join(source_dir, 'requirements.txt'), 'w') as f:
f.write('requests==2.28.1\n')
with open(os.path.join(source_dir, 'app.py'), 'w') as f:
f.write('import requests\n\ndef handler(event, context):\n response = requests.get("https://api.github.com")\n return {\n "statusCode": 200,\n "body": f"Hello from Lambda! GitHub status: {response.status_code}"\n }\n')
# Define build parameters
# runtime: The target AWS Lambda runtime (e.g., 'python3.9', 'nodejs18.x')
# build_options: Specific options for the workflow (e.g., 'uv' for Python)
build_parameters = {
"source_dir": source_dir,
"artifacts_dir": artifacts_dir,
"scratch_dir": './.aws-lambda-builders-scratch',
"runtime": 'python3.9',
"architecture": 'x86_64',
"optimizations": {},
"options": {
"artifact_executable_name": "app.py", # Entry point for Python
"handler": "app.handler"
}
}
try:
print("Starting Lambda build...")
# Initialize the LambdaBuilder
builder = LambdaBuilder(
lambda_builders_version='1.0.0', # Placeholder for internal tracking
**build_parameters
)
# Execute the build
builder.build()
print(f"Lambda function successfully built to: {artifacts_dir}")
print(f"Contents: {os.listdir(artifacts_dir)}")
# Clean up dummy files
os.remove(os.path.join(source_dir, 'requirements.txt'))
os.remove(os.path.join(source_dir, 'app.py'))
os.rmdir(source_dir)
os.rmdir(build_parameters['scratch_dir'])
os.rmdir(artifacts_dir)
except BuildError as e:
print(f"Build failed: {e}")
except Exception as e:
print(f"An unexpected error occurred: {e}")
Debug
Known issues
deprecatedThe `npm --production` flag for Node.js workflows has been deprecated. It has been replaced with `npm --omit=dev` for better exclusion of development dependencies.fixEnsure your build environment for Node.js projects uses `npm --omit=dev` instead of `npm --production`. The `aws-lambda-builders` library itself should handle this for integrated workflows, but custom Node.js build steps might need updating.
affects: >=1.63.0
deprecatedThe `bundler --without` option for Ruby workflows has been removed. This was used to exclude groups of gems.fixFor Ruby projects, remove any usage of `bundler --without` in custom build scripts. The library's internal Ruby workflows should adapt to current Bundler best practices.
affects: >=1.61.0
gotchaThe Python UV workflow, introduced in v1.62.0, is currently in beta. While it offers performance improvements, it may not be fully stable or recommended for critical production workloads without thorough testing.fixIf encountering issues with Python builds, consider falling back to the default `pip` workflow by not specifying `uv` as the package manager or build tool in your configurations until the `uv` workflow is marked stable.
affects: >=1.62.0
breakingPython 3.12 and later runtimes return Unicode characters as part of their JSON response, unlike earlier versions which returned escaped sequences. If callers expect escaped Unicode, this is a breaking change in behavior.fixAdjust calling code to handle direct Unicode characters in JSON responses for Lambda functions deployed with Python 3.12+. If escaped Unicode is strictly required by the caller, manually escape the characters in the Lambda function's response.
affects: >=Python 3.12 Lambda Runtime
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'requests'
The 'requests' library is not included in the AWS Lambda runtime environment by default.
fixInstall the 'requests' library locally and include it in your deployment package by running 'pip install requests -t .' and then zipping the contents for deployment.
Unable to import module 'lambda_function': No module named 'lambda_function'
The Lambda function's handler is misconfigured or the 'lambda_function.py' file is missing from the deployment package.
fixEnsure that the 'lambda_function.py' file is present in the root of your deployment package and that the handler is correctly set to 'lambda_function.lambda_handler'.
sam build fails to install onnxruntime==1.18.1
The 'onnxruntime' package may not be compatible with the AWS Lambda runtime environment or architecture.
fixVerify the compatibility of 'onnxruntime' with the Lambda runtime and architecture, and consider using a Lambda layer to include the package if necessary.
Error occurred while GetObject. S3 Error Code: PermanentRedirect. S3 Error Message: The bucket is in this region: us-east-2. Please use this region to retry the request
The S3 bucket used for the deployment package is in a different AWS region than the Lambda function.
fixEnsure that the S3 bucket and the Lambda function are in the same AWS region to avoid cross-region issues.
An error occurred (RequestEntityTooLargeException) when calling the UpdateFunctionCode operation
The deployment package exceeds the maximum allowed size for direct uploads to Lambda.
fixUpload the deployment package to an S3 bucket and specify the S3 bucket and key in the Lambda function update to handle larger packages.
Upgrade
Version history
1.66.0latest on PyPI · released Jul 29, 2026
Audit
Dependencies
No dependency data recorded yet.