Registry /
aws / aws-cdk-aws-lambda-python-alpha
Install & Compatibility
Where this runs
tested against v2.267.0a0 · 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.000s · 377.4MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 18.6s · import 0.000s · 378MB
399MB installed
● package 399MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
PythonFunction
✓ from aws_cdk.aws_lambda_python_alpha import PythonFunction
✗ from aws_cdk.aws_lambda_python import PythonFunction
The `-alpha` suffix is crucial for importing experimental constructs in CDK v2. Omitting it typically leads to an ImportError or attempting to use a CDK v1 construct.
PythonLayerVersion
✓ from aws_cdk.aws_lambda_python_alpha import PythonLayerVersion
This quickstart demonstrates how to define a Python Lambda function using `PythonFunction` from the `aws-cdk.aws-lambda-python-alpha` library. It dynamically creates a `lambda_code` directory with a simple `lambda_handler.py` file. The `PythonFunction` construct automatically bundles your code and its dependencies (if a `requirements.txt`, `Pipfile`, `uv.lock`, or `poetry.lock` is present in the `entry` directory) using Docker during `cdk synth`.
import os
from aws_cdk import (
App,
Stack,
aws_lambda as _lambda,
)
from aws_cdk.aws_lambda_python_alpha import PythonFunction
from constructs import Construct
# Create a dummy lambda_code directory and handler file for the example
lambda_code_dir = os.path.join(os.path.dirname(__file__), "lambda_code")
os.makedirs(lambda_code_dir, exist_ok=True)
with open(os.path.join(lambda_code_dir, "lambda_handler.py"), "w") as f:
f.write("""
import json
def handler(event, context):
print("Lambda received event:", event)
return {
'statusCode': 200,
'body': json.dumps('Hello from Python Lambda Alpha!')
}
""")
# Add a dummy requirements.txt if you want to test dependency bundling
# with open(os.path.join(lambda_code_dir, "requirements.txt"), "w") as f:
# f.write("requests\n")
class MyPythonLambdaStack(Stack):
def __init__(self, scope: Construct, construct_id: str, **kwargs) -> None:
super().__init__(scope, construct_id, **kwargs)
PythonFunction(
self,
"MyPythonLambda",
entry=lambda_code_dir, # Path to the directory containing your handler and dependencies
runtime=_lambda.Runtime.PYTHON_3_9, # Specify a supported Python runtime
index="lambda_handler.py", # Optional, defaults to 'index.py'
handler="handler", # Optional, defaults to 'handler'
# Set an environment variable (optional)
environment={
"MY_ENV_VAR": os.environ.get('MY_ENV_VAR', 'default_value')
}
)
app = App()
MyPythonLambdaStack(app, "MyPythonLambdaStack")
app.synth()
cdk --version
Debug
Known issues
breakingThis library is an 'alpha' package, meaning its APIs are experimental and under active development. Breaking changes may occur in any future version without following semantic versioning, requiring code updates when upgrading.fixRegularly check release notes for breaking changes before upgrading. Be prepared to refactor code when new versions are adopted.
affects: All alpha versions (e.g., 2.x.x-alpha.0)
gotchaBundling Python Lambda functions with this construct requires Docker to be installed and running on the machine where `cdk synth` or `cdk deploy` is executed. Without Docker, bundling will fail.fixEnsure Docker Desktop or a compatible Docker environment (e.g., Docker Engine) is installed and actively running on your development machine before synthesizing or deploying CDK stacks that use `PythonFunction` or `PythonLayerVersion`.
affects: All versions
gotchaFor reproducible builds and explicit dependency management, always commit a lockfile (e.g., `requirements.txt`, `Pipfile.lock`, `uv.lock`, or `poetry.lock`) alongside your Lambda function's source code in the `entry` directory.fixUse tools like `pip`, `pipenv`, `uv`, or `poetry` to generate and commit a lockfile specifying all transitive dependencies and their exact versions within your Lambda function's source directory.
affects: All versions
breakingMixing CDK v1 modules with CDK v2's `aws-cdk-lib` and experimental 'alpha' packages like this one is a common source of dependency resolution errors and unexpected behavior.fixEnsure your project exclusively uses CDK v2 (`aws-cdk-lib`) and its associated alpha constructs. If migrating from v1, follow the AWS CDK v2 migration guide.
affects: CDK v2 applications attempting to use v1 constructs
gotchaUsers have reported issues with bundling when using `podman` instead of `docker`, specifically related to user mapping parameters passed to the container, leading to permission denied errors.fixIf encountering issues with `podman`, consider using Docker, or investigate potential workarounds/configuration adjustments for `podman` that might resolve issues with user mapping or permissions during containerized bundling. Refer to GitHub issues for potential solutions.
affects: All versions
gotchaA `Runtime.ImportModuleError` can occur if the local file structure or dependencies of your Lambda code are not correctly resolved during bundling, or if the `index` and `handler` properties do not accurately point to your Python entry point.fixVerify that your `entry` path is correct and contains all necessary files. Ensure `index` and `handler` accurately reflect the file and function name. All Python modules imported by your Lambda should be discoverable within the bundled asset, either as part of your source or defined in a lockfile.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'aws-cdk-lib.aws_lambda_python_alpha'
The module 'aws-cdk-lib.aws_lambda_python_alpha' does not exist; the correct module is 'aws-cdk.aws-lambda-python-alpha'.
fixUse the correct import statement: 'from aws_cdk.aws_lambda_python_alpha import PythonFunction'.
[ERROR] Runtime.ImportModuleError: Unable to import module 'lambda': No module named 'orjson'
The 'orjson' package is not included in the Lambda deployment package.
fixEnsure 'orjson' is listed in your 'requirements.txt' or 'poetry.lock' and that dependencies are correctly bundled during deployment.
The command "export" does not exist
Poetry 2.0 removed the 'export' command, which is used during the bundling process.
fixUse a custom build image that installs the 'poetry-plugin-export' plugin to restore the 'export' command functionality.
ImportError: cannot import name 'core'
The 'core' module has been deprecated and removed in newer versions of AWS CDK.
fixUpdate your import statements to use 'from aws_cdk import App, Stack' instead of 'from aws_cdk import core'.
ModuleNotFoundError: No module named 'aws_cdk.aws_lambda_python_alpha'
The `aws-cdk.aws-lambda-python-alpha` package is an experimental construct library and must be installed separately from `aws-cdk-lib`.
fixInstall the package using pip: `pip install aws-cdk.aws-lambda-python-alpha`.
Upgrade
Version history
2.267.0a0latest on PyPI · released Aug 27, 2026
Audit
Dependencies
pythonrequiredRequired Python version for the library.
aws-cdk-librequiredCore AWS CDK library for defining cloud infrastructure.
constructsrequiredUnderlying construct programming model library for AWS CDK.