こんにちは。テックリードの私だ。
日々のPython開発において、`pip`から`poetry`へ移行し、そして今――私たちのチームは、Rust製パッケージマネージャーである`uv`へ完全に移行を完了した。
なぜ`uv`なのか？ 答えはシンプルだ。「速い」というレベルを超えて、開発の待ち時間という概念そのものを消滅させるからだ。しかし、`uv`の真価は単なる依存関係解決の高速化（`pip sync`の何十倍ものスピード）にだけあるわけではない。
特に、バックエンドのマイクロサービスや、C拡張モジュールを含むAI・データ処理ライブラリを自社製パッケージとして開発・ビルドするチームにおいて、WheelとSdist（ソース配布）の生成プロセスをどうハックし、ビルド時間を極限まで削るかは、デプロイパイプラインのボトルネックを直撃する死活問題である。
今回は、`uv`の内部で何が起きているのかというビルドバックエンドのメカニズムを解き明かし、キャッシュ戦略、`MANIFEST.in`の最適化、そして実務で即座に使える設定のベストプラクティスを余すところなく伝授しよう。
—
1. uvのビルドエンジンと内部プロセスの解剖
まず、`uv build` または `uv pip compile` の裏側で何が起きているのかを正しく理解する必要がある。
従来の `pip` や `poetry` は、パッケージのビルド時に PEP 517 / PEP 518 に準拠したビルドバックエンド（`setuptools`, `hatchling`, `flit-core` など）を子プロセスとして逐次起動していた。これにはプロセス起動のオーバーヘッドや、不必要なファイル群の走査によるI/Oボトルネックが存在した。
一方、`uv`はRustの並列処理能力を極限まで活かし、以下のプロセスを最適化している。
1. 環境の隔離と再利用: ビルド用の一時的な仮想環境（Build Environment）の構築をキャッシュし、極小のコストで再利用する。
2. ビルドバックエンドのインメモリ・最適化呼び出し: 可能な限りI/Oを非同期化・並列化し、Sdist（ソースディストリビューション）からWheelをビルドする際の無駄なファイルコピーを排除。
3. グローバルキャッシュの共有: マシン全体でビルド成果物（`.whl`）をハッシュ値ベースで管理し、ソースコードに変更がない限り、ビルドステップ自体を完全にスキップする。
この仕組みを理解していれば、「なぜ無駄なファイルがプロジェクトルートにあるだけでビルドが遅くなるのか」が自ずと見えてくるはずだ。
—
2. Sdist生成の最適化：MANIFEST.inによる「無駄なI/O」の排除
パッケージをビルドする際、`uv build` はまず Sdist を作成し、その中に何を含めるかを決定する。ここで、`.git` ディレクトリや巨大なログ、テスト用のダミーデータなどがうっかり含まれていると、Sdistのサイズが膨れ上がり、それを解凍して Wheel をビルドするまでのI/Oコストが跳ね上がる。
無駄なファイルをビルド対象から完全に除外し、キャッシュ効率を最大化するための `MANIFEST.in` のベストプラクティ스を見ていこう。
実践的な `MANIFEST.in` 構成例
プロジェクトルートに配置し、ビルドコンテキストを極限までクリーンに保つ。
— 除外設定 (Global Excludes) —
バージョン管理システムやIDE固有の設定ファイルは一切含めない
global-exclude .py[cod]
global-exclude __pycache__
global-exclude .git
global-exclude .env
global-exclude .DS_Store
— 開発・テスト成果物の除外 —
結合テストのデータやビルド成果物ディレクトリを明示的に除外
prune tests/
prune docs/
prune .venv/
prune build/
prune dist/
— 必要なアセットの強制インクルード —
ソースコード以外でパッケージの実行に必要な静的ファイル（設定スキーマやマイグレーション用SQL等）のみを許可
include README.md
include LICENSE
recursive-include src/my_backend/schemas .json
recursive-include src/my_backend/sql .sql
アーキテクトの知見:
`uv` はビルド時にプロジェクトのファイルツリーをスキャンする。`MANIFEST.in` で不要なディレクトリ（特に数万ファイルになりがちな `node_modules` や `.venv`、重い `tests/`）を `prune` しておくことで、スキャン時間を数ミリ秒単位で削り取ることが可能になる。
—
3. pyproject.tomlによるビルドバックエンドのモダンな定義と最適化
現代のPythonエコシステムでは、`setuptools` のレガシーな設定から、高速なモダンビルドバックエンド（例: `hatchling` や `maturin`）への移行が必須だ。ここでは、依存関係管理とビルドを `uv` と完全に統合するための `pyproject.toml` の決定版を示す。
`pyproject.toml` ベストプラクティス構成例
[build-system]
最速のビルドバックエンドの一つである hatchling を採用
requires = [“hatchling>=1.21.0”]
build-backend = “hatchling.build”
[project]
name = “my-high-performance-backend”
version = “1.2.0”
description = “高スループットな非同期バックエンドコアエンジン”
readme = “README.md”
requires-python = “>=3.11”
license = { text = “MIT” }
authors = [
{ name = “DevOps Architecture Team”, email = “devops@example.com” }
]
classifiers = [
“Programming Language :: Python :: 3.11”,
“Programming Language :: Python :: 3.12”,
“Framework :: AsyncIO”,
]
実行時依存関係
dependencies = [
“fastapi>=0.110.0”,
“uvicorn[standard]>=0.28.0”,
“pydantic>=2.6.0”,
]
[project.optional-dependencies]
dev = [
“pytest>=8.0.0”,
“ruff>=0.2.0”,
“httpx>=0.27.0”,
]
[tool.hatch.build.targets.wheel]
Wheelに含めるパッケージのルートディレクトリを明示（srcレイアウトの強制）
packages = [“src/my_backend”]
[tool.hatch.build.targets.sdist]
Sdistに含まれる不要なファイルをビルドレベルでもシャットアウト
exclude = [
“/.github”,
“/docs”,
“/tests”,
“.log”,
]
[tool.uv]
uv固有の設定：開発環境構築時にロックファイルを厳格に維持
package = true
—
4. C拡張を含むパッケージの高速ビルド術（Rust / Cython連携）
もしあなたのチームが、ボトルネックになりやすい処理（暗号化、高速シリアライゼーション、カスタムアルゴリズムなど）にC拡張やRust（`PyO3` / `maturin`）を採用しているなら、`uv` の並列ビルド戦略は劇的な効果をもたらす。
通常、C拡張のビルドはシングルスレッドで直列に実行されがちだが、`uv` は依存関係グラフの構築と並行して、ビルド可能なバックエンドを並列走査・コンパイルする。
高速ビルドを引き出す環境変数とコマンド戦略
CI/CDパイプラインやローカル環境でビルドを極限まで高速化するため、以下の環境変数をシェル（`.zshrc` や CIスクリプト）に組み込んでほしい。
コンパイル時の並列度をCPUコア数の限界まで引き上げる（Rust/C++コンパイルの必須設定）
export CARGO_BUILD_JOBS=$(nproc)
export MAKEFLAGS=”-j$(nproc)”
uvのビルドキャッシュディレクトリをCIのキャッシュストレージ（GitHub Actions Actions Cache等）に直結させる
export UV_CACHE_DIR=”${HOME}/.cache/uv”
ビルド時にリモートからのフェッチを極力抑制し、ローカルキャッシュを優先
export UV_OFFLINE=false
実際のビルドコマンド：
キャッシュを最大限に効かせつつ、並列ビルドを実行
uv build –verbose
—
5. チーム開発の生産性を爆発させる「神設定」と運用ルール
どれだけ優れたツールも、チームメンバー全員が同じ意識で使わなければ意味がない。ここからは、チーム開発で絶対に導入すべき運用ルールと設定を共有する。
1. チーム共通の `uv.lock` の厳格なコミット
`poetry.lock` と同様、`uv.lock` は必ずGitでバージョン管理すること。`uv` のロックファイルはTOML形式であり、`pip-tools` や `poetry` よりも遥かに高速にパースされるため、CIでの依存関係インストール時間が数秒で終わる。
2. エディタ（VS Code）連携の最適化
開発スピードを落とさないためには、IDEが `uv` の管理する仮想環境をダイレクトに認識している必要がある。
プロジェクトルートに `.vscode/settings.json` を配置し、インタープリタのパスを強制的に `uv` の仮想環境に向ける。
`.vscode/settings.json`:
{
// Pythonインタープリタのパスをuvが生成する標準の .venv に固定
“python.defaultInterpreterPath”: “${workspaceFolder}/.venv/bin/python”,
// リンター・フォーマッターとして超高速な ruff を統合
“[python]”: {
“editor.formatOnSave”: true,
“editor.defaultFormatter”: “charliermarsh.ruff”,
“editor.codeActionsOnSave”: {
“source.fixAll.ruff”: “explicit”,
“source.organizeImports.ruff”: “explicit”
}
},
// uv環境下でのテスト自動検出（pytest）
“python.testing.pytestEnabled”: true,
“python.testing.pytestArgs”: [
“tests”
]
}
3. Makefile によるワークフローの標準化
チームメンバーがコマンドを覚える必要すらない状態を作る。`Makefile` を用意し、ビルドからテストまでのフローを抽象化する。
`Makefile` ベストプラクティス:
.PHONY: install build test clean
開発環境の構築（uv syncによる超高速セットアップ）
install:
uv sync –all-extras
WheelとSdistの高速ビルド
build:
uv build
キャッシュをクリアしてクリーンビルド（トラブルシューティング用）
clean:
rm -rf .venv dist build .egg-info
uv cache clean
テストの実行
test:
uv run pytest -v
—
結び：エンジニアの時間を「待ち時間」から解放せよ
私たちがツールにこだわる理由はただ一つ。「思考のコンテキストスイッチを最小化するため」だ。
コードを書いて、ビルドして、テストが通るまでの間にコーヒーを淹れに行っているような開発スタイルは、現代のスピード感においては致命的な悪手である。
`uv` を導入し、今回解説した `MANIFEST.in` の最適化、ビルドバックエンドの近代化、そして環境変数のチューニングを施せば、ビルドとパッケージングのストレスは完全に消え去る。
明日からの開発フローに、この知見をフル活用してほしい。チームの生産性は、間違いなく次のステージへと加速するはずだ。