ビルド済みディストリビューションとuvでPython Lambda Layerを組んでみた

ビルド済みディストリビューションとuvでPython Lambda Layerを組んでみた

PythonのLambda Layerをコンテナなしで効率良く作成する方法を紹介します。 uvのロックファイルとLinux向けwheelを活用し、再現性のあるLayerを簡単に組み立てるレシピをまとめました。
2026.11.17

データ事業本部の大谷(おおや)です。

PythonのLambda Layerを作るとき、作業OSとLambdaランタイムのOSが違うので「コンテナを立てて作成する」パターンをよく見かけます。

一方で、PyPIにビルド済みのディストリビューション(wheel)があるパッケージであれば、コンテナなしでもLayer向けアセットは意外と素直に作れます。

今回は、uvのロックファイルを再利用してLayerを組み立てる方法をまとめてみました。

この記事で伝えたいこと

  • ネイティブ拡張を含むパッケージでも、Linux向けwheelがあればローカルからLayerを組める
  • 一般的にコンテナを使うのは「実行環境に合うバイナリを確実に作る」ためだが、wheelがあるならその手間は省ける
  • uvなら uv.lock を export して、ターゲットプラットフォーム向けに pip install するだけで再現性のあるLayerが作れる

公式ドキュメントでも、ネイティブライブラリを含むパッケージはLinux向けwheelを使う手順が案内されています。

https://docs.aws.amazon.com/lambda/latest/dg/python-package.html#python-package-native-libraries

前提

  • 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段で十分です。

  1. uv export でロック済み依存関係を書き出す
  2. uv pip install で Lambda向けplatformにインストールし、python/ をzipする

uv公式ガイドでも、zipデプロイやLayer作成で同じ流れが紹介されています。

https://docs.astral.sh/uv/guides/integration/aws-lambda/

基本コマンド

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名だけ実行時引数で受け取る 形にすると汎化できます。

mise.toml
[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 で明示します。

pyproject.toml
[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で用途別に分ける

pyproject.toml
[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タスクに寄せてしまうと日々の運用が楽になるかと思います。

この記事をシェアする

関連記事