uv add transformers を実行したのにエージェントのターミナルで ModuleNotFoundError: No module named 'transformers' が出る、あるいは error: distribution transfomers was not found と返ってくる。Antigravityで Hugging Face モデルを触り始めた直後に、多くの方がこのつまずき方をしているはずです。
私もローカルLLMの検証を始めた頃に同じ罠を踏みました。原因は1つではなく、uv の挙動・Antigravity のターミナルが見ている仮想環境・PyPI の正確な配布物名、この3つが少しずつズレているケースが大半です。順番に潰していけば、ほぼ確実に解消できます。
最初に疑うべきは、本当にタイプミスかどうか
GSCで「uv add transformers error transfomers not found」というクエリを実際に見たことがあります。よく見ると transfomers（rが1つ足りない）です。uv は Python のレジストリに対してかなり厳密なので、1文字でも違えば容赦なく落とします。
$ uv add transfomers
error: Distribution `transfomers` was not found in the registry恥ずかしい話、私も Slack に貼られた手順書をコピペしていて、原文の方が間違っていたケースに遭遇しました。落ちた時はまずここを確認してください。正しい綴りは transformers です。Antigravity のエージェントに頼んだコマンドでも、稀に同じタイポが入り込みます。
# ✅ 正しい
$ uv add transformers
Resolved 18 packages in 612ms
+ transformers==4.46.2なお、Hugging Face 関連で一緒にインストールしたくなる隣のパッケージも、綴りに注意が必要です。tokenizers（tokeniser ではない）、accelerate（accelerator ではない）、safetensors（safetensor の単数形ではない）。リストにしておくと安全です。
uv add は成功しているのに import transformers が落ちる
これが2番目に多いパターンで、しかも一番気付きにくい現象です。uv add は仮想環境（.venv）に対して書き込みを行っているのに、いざコードを実行すると別の Python が呼ばれていて、そちらに transformers が入っていない、という状態です。
切り分けは2行で済みます。
$ which python
/usr/bin/python ← システム側のPython
$ uv run python -c "import sys; print(sys.executable)"
/Users/you/project/.venv/bin/python ← uvが見ているPythonポイントは、Antigravityのターミナルやエージェントが起動された時点で .venv が activate 済みでないと、uv add で入れたパッケージはそのシェルからは見えないという挙動です。私はこれで30分以上悩みました。
解決策は3つあります。お好みでどれかを採用してください。
# 案1: 都度 uv run でラップして実行する（最も推奨）
$ uv run python script.py
# 案2: シェルセッションで仮想環境を有効化してから作業する
$ source .venv/bin/activate
$ python script.py
# 案3: pyproject.toml に script を切ってあるなら
$ uv run my-script私は普段「案1」で統一しています。理由は、Antigravityのエージェントに作業を任せた時に uv run プレフィックスがあれば仮想環境の切り替え忘れによる事故が起きないからです。activate 派は、人間がターミナルを行き来している間にエージェントが別のシェルで動き出すと、エージェント側が素のPythonを叩いて沈黙する、という問題が起きやすいです。
Antigravity のエージェントが見ているシェルが別物になっている
ターミナルでは動くのに、エージェントに「同じスクリプトを動かして」と頼むと ModuleNotFoundError になります。これも頻発します。Antigravityのエージェントは独立したシェルを開いて実行するため、人間が source .venv/bin/activate した状態を継承しません。
対策としては、pyproject.toml の [project.scripts] か、リポジトリ直下に小さなランナースクリプトを置いて、エージェントには必ずそれ経由で叩いてもらう運用が安定します。
# pyproject.toml
[project]
name = "my-llm-app"
version = "0.1.0"
requires-python = ">=3.11"
dependencies = [
"transformers>=4.46.0",
"torch>=2.4.0",
"accelerate>=1.0.0",
]
[project.scripts]
infer = "my_llm_app.cli:main"# エージェントへの依頼例
$ uv run infer --prompt "hello"こうしておけば、エージェントが python script.py ではなく uv run infer を叩く限り、必ず .venv 配下の transformers が読み込まれます。Antigravityのマネージャーサーフェスで複数エージェントに作業を振る運用を始めた途端、この種の事故は目に見えて増えるので、最初から uv run 統一で組むのが結局一番速いです。
torch のバックエンドが噛み合っていなくて起動時に落ちる
uv add transformers は通った、import もできた、なのに pipeline(...) を呼んだ瞬間に RuntimeError で落ちる。これは大抵 torch 側のバックエンドが環境と合っていません。
Mac（Apple Silicon）で起きがちなパターン:
# 落ちる例
from transformers import pipeline
pipe = pipeline("text-generation", model="meta-llama/Llama-3.2-1B")
# RuntimeError: MPS backend out of memory ...# ✅ 明示的にデバイスを指定する
import torch
from transformers import pipeline
device = "mps" if torch.backends.mps.is_available() else "cpu"
pipe = pipeline(
"text-generation",
model="meta-llama/Llama-3.2-1B",
device=device,
torch_dtype=torch.float16, # MPS なら float16 でメモリを半分に
)
print(pipe("Hello, ")[0]["generated_text"])
# 期待出力: Hello, world! のような短い続きが返ってくるLinux + NVIDIA GPU の場合は CUDA 版の torch を入れる必要があります。uv ではインデックスを指定して入れます。
# CUDA 12.4 を使っている場合の例
$ uv add torch --index https://download.pytorch.org/whl/cu124
$ uv add transformers私は最初、Mac で開発したコードをそのままLinux GPUマシンに持ち込んで、device="mps" のまま動かしてしまい、原因が transformers ではなく torch のデバイス指定だと気付くのに半日溶かしました。device は環境変数か設定ファイルに切り出しておくと使い回しが効きます。
Hugging Face のキャッシュとオフライン環境の落とし穴
社内ネットワークやプロキシ環境で Antigravity を使っている方からよく聞くのが、「ライブラリは入ったのに、モデルのダウンロードで止まる」現象です。transformers 本体は PyPI から入りますが、モデルの重みは Hugging Face Hub から別経路で取りに行きます。
# プロキシ環境で必要な環境変数
$ export HF_HUB_OFFLINE=0
$ export HTTP_PROXY=http://proxy.company.local:8080
$ export HTTPS_PROXY=http://proxy.company.local:8080
$ export HF_HOME=$HOME/.cache/huggingface # 共有ディスクなら別パスAntigravity を社内プロキシ越しで使う設定は別記事にまとめてありますので、合わせて参照してください。Antigravity のターミナルとエージェントが別シェルで動く以上、.zshrc や .bashrc への記載だけでなく、pyproject.toml か .envrc（direnv）に書いておくとエージェント側にも伝わります。
オフライン検証を強制したい場合は HF_HUB_OFFLINE=1 を付けて起動します。事前に huggingface-cli download でローカルにモデルを落としておけば、ネットワーク断でも検証が進みます。
ちなみに uv add と uv pip install は意味が違います
pip から uv に移ってきた方が必ず一度は混乱するのが、uv pip install transformers を打てば pyproject.toml に依存が追加されると思い込んでしまう問題です。実際には追加されません。uv pip install は従来の pip 互換のフロントエンドで、その場の環境にだけ入れます。pyproject.toml と uv.lock を更新するのは uv add の方です。
# pyproject.toml と uv.lock を更新する（プロジェクト依存はこちら）
$ uv add transformers
# その場限りのインストール。プロジェクトファイルは変わらない
$ uv pip install transformersエージェントがクリーンチェックアウトから環境を組み直した時に「transformers がない」と言ってきたら、最初のセットアップで uv pip install（その場限り）を使っていなかったかを疑ってください。CIマシンと開発機で環境が食い違うパターンの定番です。
Pythonのバージョン不整合が原因のことも
長く動いているプロジェクトで地味に詰まるのが、uv add transformers で取得したホイールがプロジェクトのインタプリタと合っていないケースです。transformers 自体は幅広いPythonバージョンを謳っていますが、依存している tokenizers や safetensors は特定のマイナーバージョン向けの事前ビルド済みホイールを配っています。requires-python が新しすぎて対応ホイールが無いと、uv がソースビルドにフォールバックし、コンパイルに失敗して中途半端な状態のままインポート時にエラーが出る、というたちの悪いパターンになります。
# Pythonのバージョンを明示的に固定する
$ uv python pin 3.11
$ uv sync
$ uv add transformers私は requires-python を >=3.13 のまま放置していたプロジェクトでこれを踏みました。依存パッケージの半分が <3.13 を要求していて、3.11 にピンした瞬間に全部解決した、という形です。uv python list で uv が使えるインタプリタを確認し、uv python pin で明示的に固定しておくのがおすすめです。
最後に確認したい1つだけのチェックリスト
ここまで全て試しても解消しない時は、以下を上から順に確認してください。経験上、95%は3番までで決着します。
uv pip list | grep transformersで本当に入っているかをuvの視点で確認するuv run python -c "import transformers; print(transformers.__file__)"で読み込まれているパスが.venv配下かを確認するuv lockでuv.lockが壊れていないかを確認する（壊れていたらrm uv.lock && uv lock）uv cache pruneでキャッシュをクリアし、uv sync --reinstallでクリーンインストールする
私の場合、AntigravityのAIエージェントに「環境構築まるごとお願い」と頼んで失敗した時に一番効いたのは2番目でした。__file__ がシステムPythonの site-packages を指していたら、それは仮想環境の問題です。
まずは今日、手元で uv run python -c "import transformers; print(transformers.__file__)" を1回だけ叩いてみてください。出力されたパスが .venv/ を含んでいるかどうかで、原因がパッケージ側か環境側か即座に切り分けられます。