Python uv ベストプラクティス：安定性とコラボレーションのチェックリスト

実際の運用で環境を壊すのは、多くの場合「uv が十分でない」ではなくプロセスと習慣です。このチェックリストは日常の指針として直接使えます — 一つのトラブルを避けるたびに、定時退勤が一回増えます。

推奨事項

1) uv.lock は必ずコミットする

ロックファイルは再現性の基盤です。コミットしないということは、各人・各マシン・各 CI 実行が異なる依存関係をインストールする可能性があり、バグの再現が地獄になります。ロックファイルのないプロジェクトは試着したことのない新しい靴と同じ — 実戦で初めて足に合わないことがわかります。

2) .venv はコミットしない

仮想環境はローカルの産物 — .gitignore に入れておくべきです。uv は自動的に .venv をプロジェクトの ignore に追加します。確認するだけで大丈夫。

3) 依存関係はできるだけ制約する

pyproject.toml で裸の requests は避け、requests>=2.31,<3 などより具体的に書きましょう。uv add はデフォルトで合理的な制約を追加します。手動で編集する際はあまり広い範囲を指定しないように。

4) CI では uv sync または uv pip sync を使う

# GitHub Actions の例
- run: uv sync
- run: uv run pytest

先に同期してから実行 — 環境がロックファイルと一致していることを保証します。CI の中で uv add を実行しないでください。ロックファイルを変更して予期しない diff が生まれることがあります。

5) 開発ツールは optional / dev に入れる

uv add --dev pytest ruff mypy

テスト・lint・型チェックは本番の依存関係に影響せず、wheel にもパックされません。本番イメージは uv sync --no-dev だけで済みます。

よくある誤り

誤り 1：pip と uv add を混用する

同じ venv の中で pip install と uv add を両方使わないように — ロックファイルが合わなくなります。一つのやり方を決めて徹底してください。

誤り 2：uvx をプロジェクトツールとして使う

バージョン固定が必要なプロジェクトツール（pytest、mypy など）→ uv add --dev + uv run を使う。一時的な試し使い・一回限り → uvx を使う。

誤り 3：pyproject.toml を読まずに手動で編集する

依存関係の変更は uv add / uv remove を使い、フォーマットの問題やロックファイルの更新漏れを避けましょう。

誤り 4：CI に uv をインストールしない

多くの CI は今や uv に対応しています — インストールが速く、実行も速い。公式インストーラーまたは pip install uv を使ってください。依存関係の解決に pip を使い続けることに固執しないように。

誤り 5：プロジェクトに requires-python を書かない

pyproject.toml に requires-python = ">=3.12" などを明記して、ツールと協力者に最低バージョンを知らせましょう。「私の 3.12 では動く、あなたの 3.8 では壊れる」という悲劇を防ぎます。

このチェックリストに従えば、ゼロ障害は保証できませんが、多くの遠回りを避けられます。困ったときは公式ドキュメントを確認 — ほとんどの落とし穴は既に誰かが踏んでいます。開発がうまくいくよう願っています。依存関係がきれいにインストールされ、テストが常にグリーンで、CI があなたを永遠に待たせないことを！ 🦦 （ちなみに、uv を使い始めると気づきます：pip のスピナーを待っていた時間で、猫を 3 回撫でられます。）