{"id":3408,"library":"aws-lambda-builders","title":"AWS Lambda Builders","description":"AWS Lambda Builders is a Python library (currently v1.63.0) designed to compile, build, and package AWS Lambda functions for various runtimes and frameworks. It serves as the core logic behind the 'sam build' command in the AWS Serverless Application Model (SAM) CLI. The library has an active release cadence, frequently adding support for new runtimes and improving existing build workflows.","status":"active","version":"1.63.0","language":"en","source_language":"en","source_url":"https://github.com/awslabs/aws-lambda-builders","tags":["aws","lambda","serverless","build-tool","packaging"],"install":[{"cmd":"pip install aws-lambda-builders","lang":"bash","label":"Install with pip"}],"dependencies":[],"imports":[{"note":"This is the primary class for programmatically initiating a Lambda build process.","symbol":"LambdaBuilder","correct":"from aws_lambda_builders.builder import LambdaBuilder"},{"note":"Import a specific workflow class if you're directly invoking a workflow, though LambdaBuilder typically abstracts this.","symbol":"PythonPipWorkflow","correct":"from aws_lambda_builders.workflows.python_pip.workflow import PythonPipWorkflow"},{"note":"Common exception for handling build failures.","symbol":"BuildError","correct":"from aws_lambda_builders.exceptions import BuildError"}],"quickstart":{"code":"import os\nfrom aws_lambda_builders.builder import LambdaBuilder\nfrom aws_lambda_builders.exceptions import BuildError\n\n# Create a dummy source directory with a requirements.txt and app.py\n# In a real scenario, this would be your Lambda function's source code.\nsource_dir = './my_lambda_app_source'\nartifacts_dir = './my_lambda_app_build'\n\nos.makedirs(source_dir, exist_ok=True)\nos.makedirs(artifacts_dir, exist_ok=True)\n\nwith open(os.path.join(source_dir, 'requirements.txt'), 'w') as f:\n    f.write('requests==2.28.1\\n')\n\nwith open(os.path.join(source_dir, 'app.py'), 'w') as f:\n    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')\n\n# Define build parameters\n# runtime: The target AWS Lambda runtime (e.g., 'python3.9', 'nodejs18.x')\n# build_options: Specific options for the workflow (e.g., 'uv' for Python)\nbuild_parameters = {\n    \"source_dir\": source_dir,\n    \"artifacts_dir\": artifacts_dir,\n    \"scratch_dir\": './.aws-lambda-builders-scratch',\n    \"runtime\": 'python3.9',\n    \"architecture\": 'x86_64',\n    \"optimizations\": {},\n    \"options\": {\n        \"artifact_executable_name\": \"app.py\", # Entry point for Python\n        \"handler\": \"app.handler\"\n    }\n}\n\ntry:\n    print(\"Starting Lambda build...\")\n    # Initialize the LambdaBuilder\n    builder = LambdaBuilder(\n        lambda_builders_version='1.0.0', # Placeholder for internal tracking\n        **build_parameters\n    )\n\n    # Execute the build\n    builder.build()\n\n    print(f\"Lambda function successfully built to: {artifacts_dir}\")\n    print(f\"Contents: {os.listdir(artifacts_dir)}\")\n    # Clean up dummy files\n    os.remove(os.path.join(source_dir, 'requirements.txt'))\n    os.remove(os.path.join(source_dir, 'app.py'))\n    os.rmdir(source_dir)\n    os.rmdir(build_parameters['scratch_dir'])\n    os.rmdir(artifacts_dir)\nexcept BuildError as e:\n    print(f\"Build failed: {e}\")\nexcept Exception as e:\n    print(f\"An unexpected error occurred: {e}\")\n","lang":"python","description":"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`."},"warnings":[{"fix":"Ensure 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.","message":"The `npm --production` flag for Node.js workflows has been deprecated. It has been replaced with `npm --omit=dev` for better exclusion of development dependencies.","severity":"deprecated","affected_versions":">=1.63.0"},{"fix":"For 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.","message":"The `bundler --without` option for Ruby workflows has been removed. This was used to exclude groups of gems.","severity":"deprecated","affected_versions":">=1.61.0"},{"fix":"If 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.","message":"The 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.","severity":"gotcha","affected_versions":">=1.62.0"},{"fix":"Adjust 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.","message":"Python 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.","severity":"breaking","affected_versions":">=Python 3.12 Lambda Runtime"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}