#0193（2025/07/12）Python Wheel 入門

Last updated at 2025-07-11Posted at 2025-07-11

Python Wheel 入門

生成コマンド例:

# PEP 517 推奨
python -m build --wheel  # dist/*.whl が出力される

インストール:

pip install ./dist/pkg-1.0-py3-none-any.whl  # unzip だけで完了

主要フォルダ
- pkg_name/ … ピュア Python もしくは C 拡張（.so/.pyd）
- pkg_name‑VERSION.dist-info/ … メタデータ: METADATA, RECORD, entry_points.txt
特徴
- コンパイル済み ファイルを含められる → インストール時にコンパイラ不要
- RECORD にファイルの SHA256 ハッシュが記録され、改ざん検出に利用可能

観点	Wheel (.whl)	Source Distribution (sdist)	Egg (.egg)
ビルド要否	不要（事前）	必要（インストール時）	不要（事前）
推奨度	★★★ (現在の標準)	★★ (Fallback)	★ (旧式)
プラットフォーム依存	あり (manylinux, win_amd64 等)	なし	あり
メタデータ仕様	PEP 427	PEP 517/518	非推奨独自
pip の扱い	1st choice	2nd choice	読み取り可・生成不可

レイヤーキャッシュ最適化
1. 依存パッケージを wheel キャッシュに変換
```
RUN pip wheel --wheel-dir=/tmp/wheels -r requirements.txt
```
2. アプリ層で wheel をコピーしてインストール
```
COPY --from=builder /tmp/wheels /wheels
RUN pip install --no-index --find-links=/wheels myapp[all]
```
3. 依存が変わらない限り /tmp/wheels レイヤーが再利用され、ビルド時間を大幅短縮。
マルチステージとの相性: ビルド専用イメージで heavy なツールチェーンを使い、最終イメージには wheel + runtime のみ持ち込むことで イメージを数百 MB 削減。

戦略① – Pre‑build Wheel Cache
- CI ジョブで wheel を生成 → アーティファクト保存。
- デプロイ段階では pip install --no-index --find-links で高速展開。
戦略② – プラットフォーム別 Wheel 配布
- GitHub Actions の [cibuildwheel] を使い、Linux/macos/Windows 向け wheel を一括生成。
- 成果物を PyPI もしくは私設リポジトリ（Artifactory など）へ upload。
戦略③ – セキュリティ & 再現性
- pip install --require-hashes と RECORD ハッシュでサプライチェーン攻撃をブロック。
- Tag & Release ごとに wheel ハッシュを lockfile に記録しておくと再現性◎。

C 拡張を含む wheel: manylinux タグ未対応の古い glibc で動かない → build イメージを quay.io/pypa/manylinux_2_28_x86_64 に統一。
--no-binary :all: を明示している Dockerfile で wheel が無視される → only-binary/no-binary のフラグを精査。
大規模 monorepo: サブパッケージごとに wheel を切る or namespace package で 1 wheel 化、どちらが最適か検討が必要。