
ビルド済みディストリビューションとuvでPython Lambda Layerを組んでみた
データ事業本部の大谷(おおや)です。
PythonのLambda Layerを作るとき、作業OSとLambdaランタイムのOSが違うので「コンテナを立てて作成する」パターンをよく見かけます。
一方で、PyPIにビルド済みのディストリビューション(wheel)があるパッケージであれば、コンテナなしでもLayer向けアセットは意外と素直に作れます。
今回は、uvのロックファイルを再利用してLayerを組み立てる方法をまとめてみました。
この記事で伝えたいこと
- ネイティブ拡張を含むパッケージでも、Linux向けwheelがあればローカルからLayerを組める
- 一般的にコンテナを使うのは「実行環境に合うバイナリを確実に作る」ためだが、wheelがあるならその手間は省ける
- uvなら
uv.lockをexportして、ターゲットプラットフォーム向けにpip installするだけで再現性のあるLayerが作れる
公式ドキュメントでも、ネイティブライブラリを含むパッケージはLinux向けwheelを使う手順が案内されています。
前提
- Python / Lambda / Layer の基本は知っている前提です
- 依存関係管理は uv を前提にします
- タスクランナーとして mise を使う例を載せます(必須ではありません)
- 検証イメージは Lambda ランタイム Python 3.13 / x86_64(Amazon Linux 2023)です
Linux向けwheelを直接指定してインストールする
macOSやWindows環境であっても、pyarrow や duckdb、snowflake-connector-python(v5)のようなネイティブコードを含むパッケージの Lambda互換Linux wheel を直接取得できれば、コンテナを使わずにLayerを作成できます。
Python 3.12以降のランタイムは Amazon Linux 2023(glibc 2.34)ベースのため、platformタグに manylinux_2_28_* を指定します。
pip install \
--platform manylinux_2_28_x86_64 \
--target=python \
--implementation cp \
--python-version 3.13 \
--only-binary=:all: \
<package_name>
ポイントは --only-binary=:all: です。ローカル環境向けの誤ったビルド(実行時の invalid ELF header の原因)を防ぎ、wheelが存在しない場合は確実にエラーで止めてくれます。
uvでロックを再利用してLayerを組む
ここからが本題です。アプリ本体の依存関係はすでに pyproject.toml / uv.lock で管理していることが多いと思います。Layer用に別の requirements を手メンテするのは避けたいです。
uvなら、次の2段で十分です。
uv exportでロック済み依存関係を書き出すuv pip installで Lambda向けplatformにインストールし、python/をzipする
uv公式ガイドでも、zipデプロイやLayer作成で同じ流れが紹介されています。
基本コマンド
uv export -q --no-dev --frozen --group <グループ名> \
| uv pip install --no-installer-metadata --no-compile-bytecode -r - \
--target=python \
--only-binary=:all: \
--python-platform=manylinux_2_28_x86_64 \
--python-version=3.13
rm -f layer.zip
zip -ryq layer.zip python
rm -rf python
やっていることは単純です。
| オプション | 役割 |
|---|---|
uv export --frozen |
uv.lock を再解決せず、ロック済みの依存をrequirements形式で出す |
--group <グループ名> |
Layerに入れたいdependency-groupsだけを出す |
--python-platform |
手元OSではなく、Lambda向けLinux wheelを選ぶ |
--python-version |
ランタイムのPythonバージョンに合わせる |
--only-binary=:all: |
wheel以外を拒否し、誤ってソースビルドしない |
--no-installer-metadata |
INSTALLER や REQUESTED などinstaller由来のメタを作らない |
--no-compile-bytecode |
インストール時に .pyc / __pycache__ を作らない |
miseタスクにする例
毎回フラグを覚えるのは大変なので、miseタスクにすると便利です。platform と Python バージョンは共通なので、group名だけ実行時引数で受け取る 形にすると汎化できます。
[tasks.layer]
description = "uv管理の依存関係からLambda Layerを作成する"
usage = '''
arg "<group>" help="dependency-groups のグループ名(例: snowflake, duckdb, iceberg)"
'''
vars.platform = "manylinux_2_28_x86_64"
vars.python_version = "3.13"
dir = "{{ config_root }}/src/assets/layer/{{ usage.group }}/"
run = """
uv export -q --no-dev --frozen --group {{ usage.group }} | \
uv pip install --no-installer-metadata --no-compile-bytecode -r - \
--target=python \
--only-binary=:all: \
--python-platform={{ vars.platform }} \
--python-version={{ vars.python_version }} && \
rm -f layer.zip && zip -ryq layer.zip python && rm -rf python
"""
pyproject.toml 側は、例えば次のように dependency group で明示します。
[dependency-groups]
snowflake = [
"snowflake-connector-python==5.2.0",
]
Snowflake Connector for Pythonは manylinux_2_28 向けwheelが公開されているので、この方式と相性がよいです。バージョンはチームの都合に合わせてピン留めしてください。
実行は次のとおりです。出力先ディレクトリも引数のgroup名に合わせて切り替わります。
$ mise run layer snowflake
成果物として layer.zip ができ、中身のトップレベルに python/ がある状態になります。あとは aws lambda publish-layer-version で公開すればOKです。
よく使うパッケージのパターン
データ系だと Snowflake 以外にも、DuckDB や PyIceberg をLayerに載せたい場面があります。
いずれも現行版では manylinux 向けwheelが公開されており、同じレシピで組み立てられます。
dependency groupで用途別に分ける
[dependency-groups]
snowflake = [
"snowflake-connector-python==5.2.0",
]
duckdb = [
"duckdb==2.0.0",
]
# 必要な依存は extras に任せきりにせず、バージョンを明示する例
iceberg = [
"pyiceberg[pyarrow,glue]==0.12.0",
"pyarrow==21.0.0",
"boto3==1.40.46",
]
終わりに
今回は、ビルド済みディストリビューション(wheel)とuvのロック再利用で、Python Lambda Layerを組む方法をまとめてみました。
Snowflake Connector for Python、DuckDB、PyIcebergのようなデータ系パッケージでも同じ型でいけるので、Layer作成をmiseタスクに寄せてしまうと日々の運用が楽になるかと思います。






