エンジニア諸君、ようこそ。開発環境の迷宮へ。
Pythonのプロジェクトを始めたばかりの君が、「No module named …」という呪文に絶望し、結局「とりあえず`sudo pip install`して環境を破壊する」という最悪のルートを辿るのを、私は何度も見てきた。
だが安心してほしい。今日、君は「パッケージ管理の最終兵器」を手に入れることになる。それは `uv` だ。
単なる「爆速なパッケージマネージャ」という認識は捨ててくれ。`uv` は、Pythonの歴史が抱えてきた「環境汚染」という病に対する、アーキテクチャレベルの劇薬だ。これをマスターすれば、君は一生、依存関係の地獄に悩まされることはない。
—
1. なぜ「No Module Named」は起きるのか？（病理の理解）
このエラーの本質は、「君が実行しているPython」と「君がライブラリを入れた場所」が、物理的に別の世界線に存在していることにある。
PCの中には、OS標準のPython、`pyenv`で入れたPython、`brew`で入れたPythonが同居している。これらに`PATH`という名の「優先順位リスト」が適用されるわけだが、ここがカオスだと、君はAというPythonにライブラリを入れ、BというPythonでスクリプトを実行する。当然、Bは「そんなモジュール知らん」と喚く。
2. uvの真価：shimsによる「絶対支配」
`uv` は単なる管理ツールではない。Pythonの実行環境そのものを「仮想的な箱」の中に閉じ込め、shims（シム）という仲介役を立てることで、PATHの混乱を強制的に収束させる。
君が `uv run` を叩くとき、`uv` は以下の処理を瞬時に行っている。
1. プロジェクトの `.python-version` を読み込む。
2. 必要なPythonインタプリタがなければ、即座に（そして安全に）隔離された場所にダウンロードする。
3. その環境にのみ有効な `PATH` を動的に生成し、プログラムを実行する。
これによって、グローバルな環境を一切汚さずに、プロジェクトごとに「完璧に独立した宇宙」を作れるんだ。
—
3. 実践：環境を汚染しないための「最初のセットアップ」
まずは、`uv` をインストールしよう。システムに影響を与えないよう、以下のコマンドでインストールする。
uvの公式インストーラーを実行（システム環境を汚さないホームディレクトリ管理）
curl -LsSf https://astral.sh/uv/install.sh | sh
シェル設定を読み込み直す（これでuvコマンドが使えるようになる）
source $HOME/.cargo/env
プロジェクトの初期化（ここが一番重要）
プロジェクト用のディレクトリを作り、`uv` にすべてを委任する。
mkdir my-awesome-project
cd my-awesome-project
Python 3.12をプロジェクト専用としてインストールし、環境を生成
uv python install 3.12
uv init
この瞬間、君のディレクトリには `pyproject.toml` と `.venv` というディレクトリが生成される。この `.venv` こそが、君のプロジェクトを守る「結界」だ。
—
4. 「No Module Named」を二度と見ないための運用作法
今後は、ライブラリのインストールも、スクリプトの実行も、すべて `uv` を経由する。これが黄金律だ。
ライブラリの追加
単にインストールするだけではない
pyproject.tomlに依存関係を記録し、ロックファイル(.lock)を更新して整合性を保証する
uv add requests
スクリプトの実行（魔法のコマンド）
仮想環境をアクティベートする作業は不要
uv run を使うだけで、自動的に適切な環境がフックされる
uv run main.py
もし、VSCodeを使っているなら、「コマンドパレット(Ctrl+Shift+P) > Python: Select Interpreter」を開き、`./.venv/bin/python` を選択してくれ。これでエディタ側も、君のプロジェクトと同じ宇宙を見ることができるようになる。
—
5. デバッグ：もし迷子になったら
それでもエラーが出るなら、以下のコマンドで「今、どのPythonが、どこを見ているのか」を覗き込め。
実行中のPythonが参照しているパスを確認する
uv run python -m site
ここに出力される `sys.path` のリストが、君の正解だ。もしここに君の入れたいライブラリが含まれていないなら、それはその環境に対して `uv add` を忘れているだけだ。
—
最後に：賢いエンジニアのたしなみ
君が今日学んだのは、単なるツールの使い方じゃない。「自分の実行環境を完全に制御下に置く」というプロフェッショナルの作法だ。
環境構築で悩む時間は、君の貴重な人生の浪費だ。`uv` を使えば、その時間は「コードを書くこと」や「アーキテクチャを考えること」という、もっと生産的で楽しい体験に変換される。
さあ、PATHの迷宮から抜け出し、本来のコーディングを楽しんでくれ。困ったときは、いつでもこの知見に戻ってきてほしい。応援しているよ。