uv buildが0.4.18から0.4.21まで壊れていて、ぼくのかんがえたDockerイメージビルドが影響を受けていましたが、0.4.22以降は修正されています

はじめに

「uv buildが壊れたの！！」¹ nikkieです。

最近uvで経験した事象です。

目次

• はじめに
• 目次
• uvを残さないDockerイメージビルド
• uv buildが壊れた
• uvのリポジトリのissueより
  • issue #8200 - regression: uv build silently produces empty wheels with hatchling if .gitignore is missing
  • pull request #8220 - Run uv build builds in the source distribution bucket
• 終わりに

uvを残さないDockerイメージビルド

思想が強いのは重々承知の上ですが、uv自体は（開発者には大いに価値を提供しますが）アプリケーションのユーザに価値を提供していないので、ビルドしたDockerイメージからは除きたい立場です。

uvで開発中のPythonライブラリをDockerイメージにビルドする際は

• 自作ライブラリに必要な依存をuv sync --no-install-projectでインストール
• 自作ライブラリ自体はuv buildしたwheelをuv pip install（editable installをしない措置）

と考えています。
詳しくはこちらの記事をどうぞ

Dockerfileの例はこちらにあります。

uv buildが壊れた

DockerfileではFROM ghcr.io/astral-sh/uv:python3.12-bookworm AS builderと指定しています。
そのため、このイメージに含まれるuvは自然とバージョンが上がっていきます。

上記の記事を書いた後しばらくしてビルドしたところ、できあがったイメージをrunできませんでした。
ベースイメージをghcr.io/astral-sh/uv:0.4.18-python3.12-bookwormにすることで再現します²。

% docker --version
Docker version 27.2.1-rd, build cc0ee3e

% docker build --no-cache -t uv-practice-lib:0.2.0-uv0.4.18 .
% docker run --rm uv-practice-lib:0.2.0-uv0.4.18
/usr/local/bin/python: No module named mylib

イメージの状態を見てみます。

% docker run --rm -it uv-practice-lib:0.2.0-uv0.4.18 bash

root@d72844b8f6ac:/# ls /usr/local/lib/python3.12/site-packages/
README.txt   _virtualenv.py            pip
__pycache__  kojo_fan_art-0.1.1.dist-info  pip-24.2.dist-info
_virtualenv.pth  mylib-0.1.0.dist-info         the_solitary_castle_in_the_mirror

site-packagesにmylibというディレクトリがありません。
mylib-0.1.0.dist-infoはあるのですが、mylibがないのです。
そのため、CMDでイメージに指定しているpython -m mylibは「No module named mylib」というわけですね。

site-packagesの中身はbuilderイメージからコピーしているため、builderイメージにあるuvの問題と思われました。
uv buildしたwheelを確認したところ、ソースコードを含んでいませんでした。

なお、ベースイメージをghcr.io/astral-sh/uv:0.4.22-python3.12-bookwormに上げると解決します。
（どのバージョンで壊れているかをしらみつぶしに調べた後、uvのissueを見に行きました）

% docker build --no-cache -t uv-practice-lib:0.2.0-uv0.4.22 .

% docker run --rm uv-practice-lib:0.2.0-uv0.4.22
Hello from mylib!
['kokoro', 'aki', 'fuka', 'rion', 'subaru', 'masamune', 'ureshino']

uvのリポジトリのissueより

issue #8200 - regression: uv build silently produces empty wheels with hatchling if .gitignore is missing

私がDockerイメージビルドで直面したのと同様のissueが報告されていました。
再現手順がわかりやすいです。

1. demoプロジェクトでsrc/demo/__init__.pyだけを用意
2. uv build（wheel作成）
3. unzip -l dist/demo-0.1.1-py3-none-any.whl（wheelに含まれるファイルを一覧³）

再現手順3でdemo/__init__.pyがwheelに含まれません。
これを展開してもsite-packagesにdemoディレクトリはできませんね（すなわち「No module named demo」をきたす）

pull request #8220 - Run uv build builds in the source distribution bucket

修正いただき感謝です⁴。
このプルリクエストには何が原因でどう直したかが書いてあります。

• 今回のケースはビルドバックエンドにhatchlingを使っている
• uv buildの出力先は、デフォルトでdistディレクトリ
  • ソース配布物をwheelにするとき、出力ディレクトリの下の一時ディレクトリでビルドする（dist/tempのようなイメージで理解した）
• uvはv0.4.18でdistディレクトリに*という内容の.gitignoreを置くようになった⁵
  • Add gitignore to dist directory by konstin · Pull Request #7835 · astral-sh/uv · GitHub
• このdist/.gitignoreのために、hatchlingはビルド用一時ディレクトリ（イメージ dist/temp）の中のすべてのファイルを無視し⁶、ソースコードを含まないwheelが作成された⁷
• にせのgit rootとして.gitファイルを追加して、hatchlingがファイルを無視しないようにした

uvがdist/.gitignoreを置いたことで、ビルドバックエンドにhatchlingを使うときに、開発者が想定していない振る舞いとなったということですね。
なお、このプルリクエストではテストコードも追加されているので、今後の再発はないと安心しました（テストが壊れることでリリース前に気づけるはずですので）

終わりに

直近で直面した、uv buildがソースコードを含まないwheelを作ってしまう事象についてでした。
ビルドに使うディレクトリの親に.gitignoreを置くようにしたことと、ビルドバックエンドhatchlingの振る舞いとの不整合でした。
詳細に報告いただき、そして直していただき、ありがとうございました。