{"id":5572,"library":"aws-cdk-aws-lambda-python-alpha","title":"AWS CDK Python Lambda Alpha Library","description":"The CDK Construct Library for AWS Lambda in Python, providing constructs to define and manage Python Lambda functions. It simplifies packaging and dependency management by leveraging Docker for bundling. This is an alpha package, meaning its APIs are experimental and subject to non-backward compatible changes, with breaking changes announced in release notes rather than following strict semantic versioning. Current version is 2.248.0a0 and it is under active development.","status":"active","version":"2.248.0a0","language":"en","source_language":"en","source_url":"https://github.com/aws/aws-cdk.git","tags":["aws-cdk","lambda","python","serverless","iac","alpha","docker","bundling"],"install":[{"cmd":"pip install aws-cdk.aws-lambda-python-alpha","lang":"bash","label":"Install package"}],"dependencies":[{"reason":"Required Python version for the library.","package":"python","version":">=3.9"},{"reason":"Core AWS CDK library for defining cloud infrastructure.","package":"aws-cdk-lib","version":">=2.x"},{"reason":"Underlying construct programming model library for AWS CDK.","package":"constructs","version":">=10.0.0"}],"imports":[{"note":"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.","wrong":"from aws_cdk.aws_lambda_python import PythonFunction","symbol":"PythonFunction","correct":"from aws_cdk.aws_lambda_python_alpha import PythonFunction"},{"symbol":"PythonLayerVersion","correct":"from aws_cdk.aws_lambda_python_alpha import PythonLayerVersion"}],"quickstart":{"code":"import os\nfrom aws_cdk import (\n    App,\n    Stack,\n    aws_lambda as _lambda,\n)\nfrom aws_cdk.aws_lambda_python_alpha import PythonFunction\nfrom constructs import Construct\n\n# Create a dummy lambda_code directory and handler file for the example\nlambda_code_dir = os.path.join(os.path.dirname(__file__), \"lambda_code\")\nos.makedirs(lambda_code_dir, exist_ok=True)\nwith open(os.path.join(lambda_code_dir, \"lambda_handler.py\"), \"w\") as f:\n    f.write(\"\"\"\nimport json\n\ndef handler(event, context):\n    print(\"Lambda received event:\", event)\n    return {\n        'statusCode': 200,\n        'body': json.dumps('Hello from Python Lambda Alpha!')\n    }\n\"\"\")\n# Add a dummy requirements.txt if you want to test dependency bundling\n# with open(os.path.join(lambda_code_dir, \"requirements.txt\"), \"w\") as f:\n#     f.write(\"requests\\n\")\n\nclass MyPythonLambdaStack(Stack):\n    def __init__(self, scope: Construct, construct_id: str, **kwargs) -> None:\n        super().__init__(scope, construct_id, **kwargs)\n\n        PythonFunction(\n            self,\n            \"MyPythonLambda\",\n            entry=lambda_code_dir, # Path to the directory containing your handler and dependencies\n            runtime=_lambda.Runtime.PYTHON_3_9, # Specify a supported Python runtime\n            index=\"lambda_handler.py\", # Optional, defaults to 'index.py'\n            handler=\"handler\", # Optional, defaults to 'handler'\n            # Set an environment variable (optional)\n            environment={\n                \"MY_ENV_VAR\": os.environ.get('MY_ENV_VAR', 'default_value')\n            }\n        )\n\napp = App()\nMyPythonLambdaStack(app, \"MyPythonLambdaStack\")\napp.synth()\n","lang":"python","description":"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`."},"warnings":[{"fix":"Regularly check release notes for breaking changes before upgrading. Be prepared to refactor code when new versions are adopted.","message":"This 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.","severity":"breaking","affected_versions":"All alpha versions (e.g., 2.x.x-alpha.0)"},{"fix":"Ensure 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`.","message":"Bundling 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Use 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.","message":"For 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure 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.","message":"Mixing 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.","severity":"breaking","affected_versions":"CDK v2 applications attempting to use v1 constructs"},{"fix":"If 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.","message":"Users 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Verify 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.","message":"A `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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}