Lambda Packer (BuildKit-Native)

lambda-packer is a "compiler" for AWS Lambda and Layers. Instead of running pip install on your host machine, it compiles your package_config.yaml into a BuildKit execution graph, ensuring your artifacts are always built in a runtime-correct, isolated environment.

🚀 Key Features

BuildKit-First: Zero host-side dependencies (except Docker). No more "it works on my machine" C-extension issues.
Standardized Context: Build from any folder on your machine; the tool automatically stages your source and layers.
Parallel Builds: High-performance execution using ThreadPoolExecutor and BuildKit's internal graph concurrency.
Multi-Platform: Built-in support for linux/amd64 and linux/arm64.
Deterministic ZIPs: Reproducible artifacts with fixed timestamps and sorted entries.
OCI Image Support: Build and push multi-platform Lambda images directly to a registry.

🚦 Quick Start

1. Initialize the project

uv sync

2. Run a Parallel Build

# Build with 4 parallel workers
uv run lambda-packer build --config package_config.yaml -j 4

3. Push to a Registry

Ensure you are logged into your registry (docker login), then run:

uv run lambda-packer build --config package_config.yaml --push

📖 Configuration (`package_config.yaml`)

The configuration supports absolute paths, allowing you to build Lambdas from other projects.

runtime_default: "python3.12"

layers:
  # Shared layer from an external project
  common-utils:
    path: ./common
    requirements: ./common/requirements.txt
    platforms: [linux/amd64, linux/arm64]

lambdas:
  # ZIP-based Lambda
  api-handler:
    path: ./lambdas/api
    type: zip
    layers: [common-utils]
    platforms: [linux/amd64, linux/arm64]

  # Image-based Lambda with custom tagging
  processor:
    path: ./samples/processor
    type: image
    image_tag: "my-registry.com/processor:{arch}"
    handler: "app.handler"
    layers: [common-utils]
    platforms: [linux/amd64, linux/arm64]

💻 CLI Usage

`build` command

uv run lambda-packer build [OPTIONS]

Options:

--config PATH: Path to your config YAML (default: package_config.yaml).
--dist PATH: Directory to store outputs (default: dist/).
--cache STR: BuildKit cache options (e.g., type=local,dest=.buildkit-cache).
--push: Push OCI images to the registry.
-j, --concurrency INT: Number of parallel builds (default: 1).

🏗 How it Works (Standardized Context)

The tool uses a "Staging Area" strategy to handle absolute paths and complex dependencies:

Stage: A temporary directory is created for each build task.
Map: Source code, requirements, and layers are copied/symlinked into standardized locations (src/, layer_<name>/).
Compile: A multi-stage Dockerfile is generated to reference these fixed paths.
Execute: BuildKit runs the build using this isolated staging directory as the context.

This ensures that only the necessary files are sent to Docker, making builds fast and independent of your local file structure.

🔒 Security & Determinism

All ZIP files are generated with a fixed timestamp (1980-01-01) and sorted file entries. This ensures that if your code doesn't change, the SHA-256 hash of your ZIP file remains identical, preventing unnecessary AWS Lambda deployments.

🛠 Development

Setup

git clone https://github.com/calvernaz/lambda-packer.git
cd lambda-packer
uv sync --extra dev

Running Tests

PYTHONPATH=src uv run pytest tests/

License

This project is licensed under the MIT License.

Metadata

Release files for lambda-packer 0.1.63

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for lambda-packer 0.1.63
File	Size	Uploaded
lambda_packer-0.1.63.tar.gz	16.0 kB	Mar 15, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for lambda-packer 0.1.63
File	Interpreter	ABI	Platform	Reset
lambda_packer-0.1.63-py3-none-any.whl 14.6 kB Mar 15, 2026	Python 3	none	any	Details

Total release size: 30.7 kB

Release files / lambda_packer-0.1.63.tar.gz

Download URL	lambda_packer-0.1.63.tar.gz
Size	16.0 kB
Tags	Source
SHA-256 checksum How to use checksums	`02edef1c957cf294d42c41a97e062f2625bdd3e8408fe3dacc19dfc0a9f9b934`
BLAKE2b-256 checksum How to use checksums	`e2a9668f8b7a331bcd6b25284b5979c782747e86ddbce72b396b1a893a0e9997`
Upload date	Mar 15, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.1.0 CPython/3.13.7`

Release files / lambda_packer-0.1.63-py3-none-any.whl

Download URL	lambda_packer-0.1.63-py3-none-any.whl
Size	14.6 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`3a3a44fcbaa426a888123da66c501f5afcb53c56c03f39cd5a286e9f8f2cacf1`
BLAKE2b-256 checksum How to use checksums	`900f1328940f6f517b3acbe1e15014a6739fae6dafbae618503a5c1a6318cecc`
Upload date	Mar 15, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.1.0 CPython/3.13.7`