uv-bundler
Build AWS Lambda ZIPs, Spark --py-files archives and PEX files for Linux (x86_64 or
aarch64) from your Mac. No Docker, no Linux build box.
uv tool install uv-bundler
uv-bundler --target lambda --arch aarch64
# → dist/my-fn-linux-aarch64.zip (Linux Graviton wheels, built on macOS)
Your pyproject.toml already lists the dependencies. uv-bundler asks uv
for the target's wheels (--python-platform), not your laptop's, and packs them with
your code in the layout the target runtime expects.
Not affiliated with Astral. uv-bundler is a community tool built on top of uv.
Why
pip install on a Mac fetches macOS wheels. Zip them up for Lambda or Spark, and the
first import of NumPy, orjson, pydantic-core or cryptography fails on Linux. The usual
fixes are a Docker build (sam build --use-container, a hand-written Dockerfile) or a
Linux CI job just for packaging.
uv-bundler does it in one command, on any host, in seconds, from config you check in.
Quick start
1. Describe the artifact in pyproject.toml:
[tool.uv-bundler]
project_name = "my-fn"
default_target = "lambda"
[tool.uv-bundler.targets.lambda]
format = "zip"
entry_point = "my_fn.main:run" # used by `python my-fn.zip`; Lambda calls your handler
platform = "linux"
arch = "x86_64" # or override with --arch aarch64
python_version = "3.12"
manylinux = "2014"
2. Build:
uv-bundler # → dist/my-fn-linux-x86_64.zip
uv-bundler --arch aarch64 # → dist/my-fn-linux-aarch64.zip
uv-bundler --dry-run # show the resolved config, build nothing
3. Deploy with the tools you already use (below).
Use it with
AWS Lambda — format = "zip"
Your code and its dependencies sit at the root of the ZIP, which is the layout Lambda imports from.
aws lambda update-function-code --function-name my-fn \
--zip-file fileb://dist/my-fn-linux-aarch64.zip
# handler: my_fn.handler.handler runtime: python3.12 architecture: arm64
Native dependencies work, because Lambda extracts the ZIP before importing. With SAM or
CDK, point CodeUri / Code.fromAsset at the ZIP.
Spark (EMR, Databricks, spark-on-k8s) — format = "jar" or "zip"
spark-submit --py-files dist/my-job-linux-x86_64.jar driver.py
Driver and executors both import your package and its dependencies from the archive.
Keep pyspark out of [project].dependencies: the cluster provides it. Put it in a
dev group ([dependency-groups] dev = ["pyspark"]) so you have it locally but never ship it.
.jar is a zip with a JVM-friendly manifest; PySpark accepts .jar, .zip and .egg in
--py-files. Python can't import native extensions (.so) from inside a zip on the path,
so for NumPy and similar dependencies on Spark use a PEX (see PySpark's Python package
management docs).
Airflow, cron, schedulers, Spark with native deps — format = "pex"
python dist/my-job-linux-x86_64.pex
A PEX is a single executable file containing a whole
environment, native extensions included. Needs pex on PATH when you build
(uv tool install pex).
Slim mode — dependencies already on the target
uv-bundler --slim # → dist/my-job-linux-x86_64-slim.jar, your source only
For EMR clusters with bootstrapped libraries, Lambda Layers, or Airflow workers with a shared environment. Slim builds don't resolve anything.
How it works
- Reads
[tool.uv-bundler], applies CLI overrides, checks that the entry-point module exists. uv pip compile --python-platform x86_64-manylinux2014 …pins versions for the target.uv pip install --target … --python-platform …downloads the matching wheels. (PEX targets skip this step, because pex resolves the lockfile itself.)- Assembles the archive: sources and dependencies at the root, plus a
__main__.pysopython artifact.zipruns yourentry_point.
Compared with other approaches
| Approach | Docker? | Output | Notes |
|---|---|---|---|
| uv-bundler | No | ZIP, --py-files JAR/ZIP, PEX |
One config for all three; macOS and Linux hosts tested in CI |
pex --platform … |
No | PEX only | What uv-bundler uses for PEX. Use it directly if PEX is all you need |
pip download --platform … --only-binary :all: + a zip script |
No | Whatever you script | Same idea; you maintain the script and the layout |
sam build --use-container, Docker builds |
Yes | Lambda | Can compile sdist-only packages, which uv-bundler can't |
venv-pack / conda-pack |
Linux build host | Spark archives | Packs an environment that must already exist on Linux |
Limitations
- Needs wheels for the target. A dependency that only publishes an sdist with native
code can't be compiled for another platform. Pin a version that ships a matching wheel,
change
manylinux/python_version, or build that artifact on Linux. Pure-Python sdists are fine. - Native extensions in JAR/ZIP only load where the archive is extracted (Lambda yes,
--py-filesno). uv-bundler warns when a JAR contains them. Use PEX otherwise. - Resolves from
pyproject.toml, notuv.lock. Versions are pinned at build time for the target, so they can differ from your local lock.
How it's tested
Every push runs artifacts.yml. It builds the
sample projects on Linux x86_64, Linux aarch64 and macOS (Apple Silicon),
always targeting a platform other than the build host. Each artifact then runs on native
hardware the way production runs it:
- the Lambda ZIP is invoked through AWS's own Lambda runtime image,
- the Spark JAR and ZIP run with
spark-submit --py-filesin the official Spark image, with pyspark not bundled, - the NumPy/pandas PEX runs in a clean
python:3.10-slimcontainer.
Run the same checks locally with make -C validation test-artifacts.
Configuration reference
[tool.uv-bundler]
project_name = "analytics-engine" # artifact filename prefix
default_target = "spark-prod" # used when --target is omitted
output_base = "./dist" # output directory (OUT_DIR env var wins)
[tool.uv-bundler.targets.spark-prod]
format = "jar" # "jar" | "zip" | "pex"
entry_point = "app.main:run" # module.submodule:function
platform = "linux" # "linux" | "macos" | "windows"
arch = "x86_64" # "x86_64" | "aarch64"
python_version = "3.12" # default 3.12
manylinux = "2014" # "2010" | "2014" | glibc minor, e.g. "31"
compression = "deflated" # "deflated" | "stored"
exclude = ["tests/*", "*.pyc"] # glob patterns, relative to the project root
extra_files = { "config/prod.yaml" = "resources/config.yaml" } # source → path in archive
slim = false # true = source only, no dependencies
slim_exclude = ["tests/**", "*.pyi"] # extra excludes applied only to slim builds
Artifacts are named <project_name>-<platform>-<arch>[-slim].<format>.
CLI reference
uv-bundler [OPTIONS]
-t, --target TEXT Target name from [tool.uv-bundler.targets.*]
-p, --project PATH Project directory containing pyproject.toml (default: .)
--arch TEXT Override arch (x86_64 | aarch64)
--platform TEXT Override platform (linux | macos | windows)
--python-version TEXT Override Python version (e.g. 3.12)
--manylinux TEXT Override manylinux tag (e.g. 2014, 28)
--slim Bundle source only
--dry-run Print the resolved config without building
Troubleshooting
"failed to resolve/install dependencies" mentioning a source build. A dependency has no wheel for the target. See Limitations.
"'uv' not found on PATH" / "'pex' not found on PATH". brew install uv (or see
uv's install docs), and
uv tool install pex for PEX targets.
ImportError for a native module when running a JAR/ZIP in place. Python can't load
.so files from inside a zip. Use format = "pex", or deploy somewhere that extracts the
archive, as Lambda does.
Development
git clone https://github.com/amarlearning/uv-bundler.git && cd uv-bundler
make setup # .venv with dev deps (needs uv)
make fmt && make lint && make type && make test
make -C validation test-artifacts # real-runtime checks (needs Docker + pex)
Branches feature/<desc> / fix/<desc>, imperative commit subjects of 50 characters or
fewer, and docs updated whenever behavior changes. See AGENTS.md for the
architecture.
License
Metadata
Release files for uv-bundler 2.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| uv_bundler-2.1.0.tar.gz | 103.9 kB | With provenance | Details for uv_bundler-2.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| uv_bundler-2.1.0-py3-none-any.whl | Python 3 | none | any | Details for uv_bundler-2.1.0-py3-none-any.whl |
Total release size: 125.3 kB
Release files / uv_bundler-2.1.0.tar.gz
| Download URL | uv_bundler-2.1.0.tar.gz |
|---|---|
| Size | 103.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
465ac60c67c4040f12e015fcf45d8b58fbec76c9008575ccb47e4a544d53c96e
|
|
BLAKE2b-256 checksum How to use checksums |
86c4959f2f79e90cafb03125ffdc7040460f6a44868cdea60f52447081157557
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.
Transparency logRelease files / uv_bundler-2.1.0-py3-none-any.whl
| Download URL | uv_bundler-2.1.0-py3-none-any.whl |
|---|---|
| Size | 21.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
7db82e1059b8354de1c8ad9a9c3543f13da288641c10be1a87de45916e1a8d1d
|
|
BLAKE2b-256 checksum How to use checksums |
1baf259510bd10e44080d8350f17c2e9500dd3119e466444aeabb82690a19ca2
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.
Transparency logSecurity for uv-bundler 2.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for uv_bundler-2.1.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.