uv add でPython機械学習パッケージがインストールできないときの対処法

uv add transformers を実行したら謎のエラーが出た——Antigravity AI の開発環境を作ろうとしてこのパターンで詰まった方は多いと思います。

uv は非常に高速な Python パッケージマネージャーで、pip の代替として急速に普及しています。ただ、機械学習系のパッケージは依存関係が複雑で、uv 特有のはまりポイントがいくつかあります。

よくあるエラーパターンと原因

エラー1: Python バージョン不一致

error: No solution found when resolving dependencies:
  × No versions of `torch>=2.0.0` found for Python 3.13

torch や transformers は Python の特定バージョンにしか対応していません。Python 3.13 はまだ多くの ML ライブラリが未対応です。

解決策：Python バージョンを明示的に指定する

# Python 3.11 で新しいプロジェクトを作成
uv init --python 3.11 myproject
cd myproject
 
# または既存プロジェクトで Python バージョンを変更
uv python pin 3.11

これだけで多くのエラーが解消します。ML系プロジェクトは現時点では Python 3.10 〜 3.11 が最も安定しています。

エラー2: 依存関係の競合

error: Because `package-a` requires `numpy<1.24` and `transformers` requires `numpy>=1.24`,
       we can't install both.

複数のパッケージが同じパッケージの互いに非互換なバージョンを要求しているケースです。

解決策：インストール順序を変えるか、制約を明示する

# 重いパッケージから先に追加する（依存解決の基準になりやすい）
uv add torch
uv add transformers
uv add accelerate
 
# または制約を明示する
uv add "numpy>=1.24,<2.0"
uv add transformers

また、uv の --no-deps フラグで依存関係を無視して強制インストールする方法もありますが、これは最終手段です。動作が壊れるリスクがあります。

エラー3: CPU/CUDA 版の torch 競合

error: torch 2.1.0+cu118 and torch 2.1.0+cpu cannot coexist

CUDA 版と CPU 版の PyTorch が混在しています。

解決策：インデックスURLを指定してCUDA版を明示する

# CUDA 11.8 版を指定してインストール
uv add torch --extra-index-url https://download.pytorch.org/whl/cu118
 
# または pyproject.toml に設定を追加

pyproject.toml に書く場合：

[tool.uv.sources]
torch = { index = "pytorch-cu118" }
 
[[tool.uv.index]]
name = "pytorch-cu118"
url = "https://download.pytorch.org/whl/cu118"
explicit = true

これで uv add torch するとCUDA版が優先されます。

エラー4: ビルドエラー（コンパイルが必要なパッケージ）

error: Failed to build `pyarrow==14.0.0`
  × Failed to run `cargo build`...

pyarrow や sentencepiece などは Rust/C++ のコンパイルが必要な場合があります。

解決策：ビルド済みのwheelを使う

# binary のみを使う（コンパイルなし）
uv add pyarrow --prefer-binary
 
# または古い安定バージョンを指定（wheel が確実に存在する）
uv add "pyarrow==13.0.0"

Antigravity AI の開発環境を一発で作る

上記のポイントを踏まえた、Antigravity + ML開発環境の推奨セットアップです。

# 1. Python 3.11 でプロジェクト作成
uv init antigravity-project --python 3.11
cd antigravity-project
 
# 2. PyTorch を先に追加（CPU版 or CUDA版を選択）
# CPU版（手軽に試したい場合）
uv add torch torchvision torchaudio --extra-index-url https://download.pytorch.org/whl/cpu
 
# CUDA版（GPU環境の場合、cu118をcu121等に変更）
# uv add torch torchvision torchaudio --extra-index-url https://download.pytorch.org/whl/cu118
 
# 3. Transformers と関連ライブラリを追加
uv add transformers accelerate datasets
 
# 4. 開発ツール
uv add --dev jupyter ipykernel
 
# 5. 確認
uv run python -c "import torch; print(torch.__version__, torch.cuda.is_available())"

pip との使い分け

uv が便利とはいえ、まだ pip のほうがスムーズな場面があります。

uv が有利な場面: 新規プロジェクト、依存関係の整合性を厳密に管理したい場合、requirements.txt → pyproject.toml への移行

pip のほうが楽な場面: 既存の requirements.txt ベースのプロジェクト、Jupyter Notebook のインライン !pip install、公式ドキュメントの pip install コマンドをそのまま試したい場合

慣れるまでは「新規プロジェクトは uv、既存は pip」という使い分けが現実的です。

エラーが解消しないときの最終手段

それでも解決しない場合は、仮想環境をリセットして一から作り直すのが最速です。

# .venv を削除して再作成
rm -rf .venv
uv sync
 
# または uv.lock も含めてリセット
rm -rf .venv uv.lock
uv add torch transformers  # 再度追加

uv.lock は依存関係のスナップショットなので、これを消すと依存解決がゼロからやり直しになります。問題のあるバージョンの組み合わせが記録されていた場合は、これで解消することがあります。

uv add と uv pip install を混同しない

ML 環境構築でもう一つ多いのが、uv add と uv pip install を取り違えるケースです。名前は似ていますが役割がはっきり違います。

uv add torch … pyproject.toml に依存として記録し、uv.lock を更新します。プロジェクトの再現性を保ちたいときはこちらです。
uv pip install torch … pip 互換のインターフェースで、その場で .venv に入れるだけです。pyproject.toml は変更しません。

私がよくやってしまう失敗は、uv pip install で動作確認だけして満足し、pyproject.toml に依存を書き戻し忘れることです。別のマシンで uv sync した瞬間に torch が無くて気づきます。「試すときは uv pip install、確定したら uv add で記録する」と切り分けておくと、この種の取りこぼしが減ります。

依存解決が厳しすぎるときは index-strategy を緩める

uv は既定で「最初に見つかったインデックスのバージョン」を優先する、やや厳しめの依存解決をします。PyTorch のように複数のインデックス（PyPI と pytorch.org）にまたがるパッケージでは、この既定動作が「解が見つからない」の原因になることがあります。

# すべてのインデックスを横断してから最適なバージョンを決める
uv add torch --index-strategy unsafe-best-match

unsafe という名前で身構えてしまいますが、実際の挙動は「複数インデックスを全部見てから決める」だけです。社内ミラーと PyPI を併用するような環境でも有効です。エラー2の競合が CUDA 版 torch がらみで起きているときは、まずこのフラグを試すと一気に解けることがあります。

手元で試して分かったこと

2014年から個人開発でアプリを作り続けていますが、壁紙アプリ向けに画像を分類する前処理を手元の Mac で動かそうとしたとき、まさに torch と pyarrow のビルドで半日溶かしたことがあります。最終的に効いたのは「Python を 3.11 に固定する」「torch を CPU 版で先に入れる」「pyarrow は --prefer-binary で wheel を取りに行く」の3点で、結局この記事で並べた順番そのままでした。

エラーメッセージは長く複雑に見えても、原因は Python バージョン・インデックス指定・ビルドの3カテゴリにほぼ収まります。まず「今ぶつかっているのはどのカテゴリか」を切り分けるのが、遠回りに見えて一番の近道だと感じています。同じところで止まっている方の時間が、少しでも短く済めば嬉しいです。