AI エンジニアのトラックと、uv による開発環境

解決する問題

新しい AI エンジニアがチームに加わります。初日の作業は簡単です。プロジェクトを自分のノートパソコンで動かすことです。README には「python main.py を実行」と書かれています。実行すると ModuleNotFoundError: No module named 'httpx' が出ます。プロジェクトを書いた人のマシンでは、同じコマンドが問題なく動きます。

調べてみると、作者のマシンでは 2 年もの間、どのプロジェクトが必要としたパッケージもすべて同じ Python に溜まり続けていたことが分かります。このプロジェクトがどのパッケージに依存しているかは、どこにも書かれていません。書かれているのは「自分のマシンでは動く」ということだけです。新しい同僚は半日かけて、パッケージを一つずつ探して入れることになります。そして最後には、そのうちの一つが別のバージョンになっていて、結果も食い違ってしまいます。

プロの開発チームは、この問題に一つの答えを持っています。プロジェクトごとに独立した環境を用意し、その環境に何が入っているかをファイルに書いておくのです。そうすれば、誰でも一つのコマンドで、まったく同じ環境を作れます。この章では uv を使ってそれを作ります。そして、コースの残りの部分でもずっとそれを使います。

この章を終える頃には

• 通常のインストーラーと uv python install の両方で Python をインストールでき、2 つの違いを説明できる
• pip とは何かを説明でき、このコースが代わりに uv を使う理由を言える
• uv init、uv add、uv run、uv venv で、独立したプロジェクト環境を作って実行できる
• 例を使って、プロジェクトをシステムの Python で動かしてはいけない理由を示せる
• VS Code や PyCharm で、プロジェクト自身のインタープリターを選べる

前提条件: ターミナルでフォルダを移動すること（cd）と、コマンドを実行すること。この章はコースの最初の章なので、ほかには何も必要ありません。

このトラックの進め方

このコースはキャリアトラックです。各章は 1 回の授業のようなもので、最後は自分のマシンで実行する作業で締めくくられます。初めの章では、プロの仕事の土台を作ります — 環境、Git、プロジェクト構成、設定です。その後に、読みやすく整った Python、テスト、API、データベース、RAG、セキュリティ、デプロイが続きます。

最初に言っておきたいことが一つあります。会社では、AI エンジニアのコードは「動く」というだけでは受け入れられません。ほかの人が自分のマシンで動かせるか、誰かがレビューできるか、6 か月後にも誰かが理解できるか — そうしたことも仕事の一部です。ですからこのコースの実習はすべて、実際のチームのリポジトリに入れるつもりで作られています。そして、その習慣の最初の一歩が環境なのです。

Python のインストール：2 つの方法

方法 1 — 通常のインストーラー。 python.org から 3.12 のインストーラーをダウンロードして実行します。Windows では、最初の画面で Add python.exe to PATH にチェックを入れてください。チェックしないと、ターミナルが python コマンドを認識しません。macOS では、python.org の .pkg を実行すれば十分です。Linux では、通常 python3 がすでに入っています — これについては後で注意があります。

確認するには：

python --version
Python 3.12.0

macOS と Linux では、コマンドは python3 --version であることが多いです。

方法 2 — uv を使う。 uv は、Python のバージョン、プロジェクトの環境、パッケージを一つで扱えるツールです。まず uv をインストールします。macOS と Linux では：

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows の PowerShell では：

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

それから、新しいターミナルを開きます：

uv --version
uv 0.9.1 (9887ef5bd 2025-10-09)

バージョン番号は違うかもしれません。次は Python です：

uv python install 3.12
Installed Python 3.12.11 in 27.42s
 + cpython-3.12.11-windows-x86_64-none (python3.12.exe)

時間と、末尾のプラットフォーム名は、みなさんのマシンでは違います。uv がインストールした Python は、独自のフォルダに置かれていることに注目してください。マシンのメインの Python には触れず、PATH も変更しません。

2 つの方法は共存でき、どちらもこのコースで使えます。違いはこうです。通常のインストーラーはコンピューター全体で 1 つの Python を用意します。uv python install は、プロジェクトが必要に応じて選ぶ Python を用意します。あるプロジェクトが 3.12 を、別のプロジェクトが 3.13 を必要としても、お互いの邪魔にはなりません。

pip とは何か、なぜ uv を使うのか

Python の外部パッケージ — httpx、pydantic、fastapi — は PyPI というリポジトリにあります。それを取ってくるための伝統的なツールが pip で、Python に付属しています。インターネット上のほぼすべてのチュートリアルが pip install ... と書いています。

pip はうまく動きますが、役割は一つだけ、パッケージをインストールすることです。しかも pip を実行した Python に インストールします。プロのプロジェクトでは、ほかのことにも別のツールが必要でした：

• 適切な Python のバージョンを用意すること — 別のツール
• 独立した環境を作って有効化すること — python -m venv を実行し、手作業で activate
• プロジェクトが必要とするものを記録すること — 手作業で、ファイルに。よく忘れられる
• 使われた全パッケージの正確なバージョンを固定すること（ロックファイル） — さらに別のツール

uv はこの 4 つをすべて一つのツールで行い、しかもずっと速く行います。何より重要なのは、uv add で何かを追加すると、それがプロジェクトのファイルに 自動的に 書き込まれることです。「インストールしたけど、記録し忘れた」— 先ほどの新しい同僚の問題の根本原因 — は、この方法では起こりえません。

ですからこのコースでパッケージや環境が出てくるところでは、常に uv を使います。ほかの場所で pip install を見かけたら、uv での対応はほぼいつも uv add です。

プロジェクトにシステムの Python を使わない理由

「システムの Python」とは、コンピューターに直接インストールされた Python のことです。環境を有効化せずにターミナルで python と打つと、これが動きます。プロジェクトのパッケージをこれにインストールすると、3 つの問題が起きます。

1. 全員が同じ部屋を共有する。 あるプロジェクトは pydantic 1 を、別のプロジェクトは 2 を必要とします。システムの Python には一つのバージョンしか入れられないので、一方を直すと他方が壊れます。
2. 依存関係が見えなくなる。 そのパッケージは、古い別のプロジェクトのためにすでにインストールされています。そのため新しいプロジェクトは動きます — しかし、プロジェクトのどこにも、そのパッケージが必要だとは書かれていません。自分のマシンではエラーは出ません。エラーが出るのは同僚のマシンや、サーバーの上です。
3. オペレーティングシステムがそれを使っている。 macOS と Linux では、一部のシステムツールがその Python 上で動きます。そのパッケージを変えると、それらが壊れることがあります — だから最近の Linux では、システムの Python への直接のインストールがブロックされているのです。

二番目の問題が最も危険です。なぜなら 気づかれない からです。この章を書いたマシンのシステムの Python には、古い作業の名残として httpx、pydantic、rich がまだ入っています。だからそこでは、どのスクリプトも「動いて」しまいます。そしてまさにそのせいで、スクリプトが本当に何を必要としているのかを、そこから知る方法がないのです。

よくある誤解は「自分のマシンで動くから、問題ない」です。 システムの Python で動くスクリプトが証明するのは、いつか自分のマシンにそのパッケージが入ったことだけです。プロジェクト自身が何を必要とするかが証明されるのは、プロジェクト自身のファイルから、空の環境にすべてをインストールし、そこでスクリプトが動いたときだけです。

uv で最初のプロジェクト

作業用フォルダの中で：

uv init hello-ai --python 3.12
Initialized project `hello-ai` at `D:\ai-lab\hello-ai`

（末尾のパスは、みなさんのフォルダになります。この章の出力では、パスを短くしています。）uv init は新しいフォルダを作り、その中に次を作ります：

hello-ai/
├── .git/
├── .gitignore
├── .python-version
├── README.md
├── main.py
└── pyproject.toml

いちばん大事なのは pyproject.toml です — プロジェクトの身分証明書のようなものです：

[project]
name = "hello-ai"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.12"
dependencies = []

dependencies = [] — このプロジェクトはまだ外部のパッケージを必要としません。.python-version には 3.12 と書かれているだけです。これは、このプロジェクトがどの Python で動くかを表しています。そして uv init は、Git リポジトリと .gitignore も作ってくれています。これらは次の章で使います。

では実行してみましょう：

cd hello-ai
uv run main.py
Using CPython 3.12.11
Creating virtual environment at: .venv
Hello from hello-ai!

最初に uv run を実行したとき、uv は .venv フォルダを自動で作りました — これがプロジェクトの独立した環境です。その後、その環境の Python で main.py を実行しました。何かを有効化する必要はありませんでした。

uv add：パッケージを追加して、記録する

AI エンジニアが扱うほとんどのプロジェクトは何らかの API を呼び出すので、最初のパッケージは HTTP クライアントの httpx です。それに、.env ファイルを読むための python-dotenv も加えます：

uv add httpx python-dotenv
Resolved 9 packages in 119ms
Installed 8 packages in 92ms
 + anyio==4.15.1
 + certifi==2026.7.22
 + h11==0.16.0
 + httpcore==1.0.9
 + httpx==0.28.1
 + idna==3.20
 + python-dotenv==1.2.3
 + typing-extensions==4.16.0

2 つのパッケージを頼んだのに、8 つ入りました。残りは httpx 自身の依存関係で、uv が自動的に見つけたものです。この作業を行うときは、バージョン番号がもっと新しいかもしれません。

次に pyproject.toml を見てみましょう：

[project]
name = "hello-ai"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.12"
dependencies = [
    "httpx>=0.28.1",
    "python-dotenv>=1.2.3",
]

1 つのコマンドで 3 つのことが行われました。パッケージは .venv にインストールされ、pyproject.toml にはプロジェクトがそれらを必要とすることが記録され、そして uv.lock という新しいファイルができて、8 つのパッケージすべての正確なバージョンを固定しました。ロックファイルについては、コースの少し後で詳しく扱います。今はこれだけ分かっていれば十分です。リポジトリをクローンした同僚が uv sync を実行すると、まさにこの 8 つのバージョンが手に入ります。

何かを取り除くには uv remove を使います：

uv remove python-dotenv
Resolved 8 packages in 21ms
Uninstalled 1 package in 11ms
 - python-dotenv==1.2.3

これも両方の場所で働きます。.venv からパッケージを取り除き、pyproject.toml からも削除します。

uv venv と、手作業での有効化

uv run が環境を作って使ってくれるので、このコースではたいていそれだけで十分です。ただ、ときには空の環境だけが必要になることもあります — たとえば、まだ pyproject.toml がない古いプロジェクトなどです。その場合は：

uv venv --python 3.12
Using CPython 3.12.11
Creating virtual environment at: .venv
Activate with: .venv\Scripts\activate

最後の行は Windows の PowerShell のものです。ここでオペレーティングシステムによって違いが出ます：

# Windows (PowerShell)
.venv\Scripts\activate

# macOS / Linux
source .venv/bin/activate

有効化されると、プロンプトの先頭に (hello-ai) か (.venv) が付き、素の python コマンドがその環境の Python を実行します。抜けるには deactivate を使います。uv run を使えば、こうしたことは一切必要ないことを覚えておいてください。それが uv run の利点で、チームの README に uv run と書いておくのは安全な選択です。「有効化を忘れた」という状態が、そもそも存在しないからです。

エディターをプロジェクトの Python に向ける

プログラムはターミナルで実行されますが、エディターは import httpx の行に赤い下線を引いています — これは、たいてい、エディターが別の Python を見ていることを意味します。

VS Code： Microsoft の Python 拡張機能をインストールします。それからプロジェクトのフォルダを開き、Ctrl + Shift + P（macOS では Cmd + Shift + P）を押して → Python: Select Interpreter → .venv の中の Python を選びます。一覧に出てこない場合は、Enter interpreter path を使ってそのパスを指定します。Windows では .venv\Scripts\python.exe、macOS/Linux では .venv/bin/python です。

PyCharm： Settings → Project → Python Interpreter → Add Interpreter → Add Local Interpreter → 既存の環境を選び、同じパスを指定します。最近のバージョンでは、uv の環境タイプも直接選べます。

エディターがどの Python を使っているかを確かめる一番簡単な方法は、エディター内蔵のターミナルで次を実行することです：

import sys

print(sys.executable)

パスの末尾は、プロジェクトの .venv の中になっているはずです — たとえば ...\hello-ai\.venv\Scripts\python.exe のように。パスの始まりはフォルダによって違うので、ここでは出力全体は載せていません。

完全な例

hello-ai プロジェクトの中に、env_check.py というファイルを作ってください。これは小さな「環境チェック」のスクリプトです。チームに新しく加わった人が、最初にこのようなものを実行すると、すべてが正しい場所にあることを確かめられます：

import sys
from importlib.metadata import version
from pathlib import Path


def main() -> None:
    in_venv = sys.prefix != sys.base_prefix
    print(f"Python      : {sys.version_info.major}.{sys.version_info.minor}")
    print(f"In a venv   : {in_venv}")
    print(f"Env folder  : {Path(sys.prefix).name}")

    import httpx  # installed with `uv add httpx`

    print(f"httpx       : {version('httpx')}")
    print(f"Client ready: {httpx.Client is not None}")
    print("Hello, AI engineer.")


if __name__ == "__main__":
    main()

プロジェクトの中から実行します：

uv run env_check.py

Python      : 3.12
In a venv   : True
Env folder  : .venv
httpx       : 0.28.1
Client ready: True
Hello, AI engineer.

では、同じファイルを 空の 環境で実行してみましょう。ファイルは別のフォルダにコピーされ、そこに uv venv --python 3.12 で環境が作られました。そして、その環境の Python で直接ファイルを実行します（Windows では .venv\Scripts\python env_check.py、macOS/Linux では .venv/bin/python env_check.py）：

Python      : 3.12
In a venv   : True
Env folder  : .venv
Traceback (most recent call last):
  File "env_check.py", line 20, in <module>
    main()
  File "env_check.py", line 12, in main
    import httpx  # installed with `uv add httpx`
    ^^^^^^^^^^^^
ModuleNotFoundError: No module named 'httpx'

（お使いのマシンでは、トレースバックにファイルのフルパスが表示されます。ここではファイル名だけを残しています。）

このスクリプトのいくつかの判断には注目する価値があります。

sys.prefix != sys.base_prefix — Python 自身が、仮想環境の中で動いているかどうかを知っています。sys.base_prefix は、環境を作るもとになった基本の Python で、sys.prefix は今動いている Python です。両者が違えば、環境の中にいることになります。

フルパスではなく、フォルダ名 — Path(sys.prefix).name は、最後の部分である .venv だけを表示します。フルパスは、マシンごとに違います。名前は、誰にとっても同じです。チェックスクリプトの出力がマシン固有の情報を含まないほど、チャットでチーム内の比較がしやすくなります。

関数の途中にある import httpx — 通常、import はファイルの先頭に書きます。そして先頭に書くべきです。ここでは意図的に途中に置いています。そうすると、空の環境では最初の 3 行が表示されてからエラーが出ます。エラーの出力そのものが物語を語ります：Python 3.12 は問題なく、環境も有効になっている。でもその環境には httpx がない。直し方は uv add httpx です — あるいは、プロジェクトの pyproject.toml にすでに書かれていれば uv sync です。

version('httpx') — importlib.metadata は、パッケージのバージョンを読むための標準的な方法です。すべてのパッケージが __version__ を持っているわけではありませんが、インストールされたパッケージには必ずメタデータがあります。

うまくいかないとき

The term 'uv' is not recognized as the name of a cmdlet, function, script file, or operable program（macOS/Linux では uv: command not found） uv はインストールされていますが、入力しているターミナルがインストールより前に開かれたため、新しい PATH を知りません。ターミナル（VS Code の場合はエディター全体）を閉じて、開き直してください。

error: No pyproject.toml found in current directory or any parent directory プロジェクトのフォルダの外で uv add を実行しました。uv add はプロジェクトのファイルに書き込むので、プロジェクトがなければ書き込む先がありません。プロジェクトのフォルダに cd で移動するか、新しいプロジェクトなら先に uv init を実行してください。

ModuleNotFoundError: No module named 'httpx' スクリプトを実行している Python に、そのパッケージがありません。よくある原因は二つです。そのパッケージが uv add で追加されていないか、uv run ではなく素の python でスクリプトを実行したため、プロジェクトの環境ではなくシステムの Python が動いてしまったかです。uv run env_check.py で実行してください。

error: Failed to spawn: hello.py と、それに続く Caused by: program not found uv run に、現在のフォルダにないファイル名を渡しました。たいていは綴りの間違いか、違うフォルダにいるかです。ファイルが見つからなかったため、uv は代わりに同じ名前のプログラムを探しました。だからメッセージが不自然に読めるのです。

× No solution found when resolving dependencies と、それに続く Because htpx was not found in the package registry ... パッケージ名の綴りの間違い（htpx）です。良いニュースは、失敗した uv add は何も変えないことです — pyproject.toml と uv.lock は元のままです。綴りを直して、もう一度実行してください。

.venv\Scripts\activate : File ... cannot be loaded because running scripts is disabled on this system PowerShell のセキュリティポリシーです。Set-ExecutionPolicy -Scope CurrentUser RemoteSigned を一度実行して、新しいターミナルを開いてください。あるいは有効化をスキップして、すべてを uv run で実行しても構いません。

やってみよう

マシンに uv と Python 3.12 の準備ができたら、新しいプロジェクトを作ってください：

1. uv init my-first-agent --python 3.12 でプロジェクトを作り、uv add httpx でパッケージを一つ追加する
2. 上の env_check.py ファイルを、プロジェクトに正確に書き写し、uv run env_check.py で実行する
3. pyproject.toml を開き、httpx が dependencies に書かれていることと、プロジェクトに uv.lock ファイルができていることを示す
4. プロジェクトを VS Code か PyCharm で開き、プロジェクトの .venv をインタープリターとして選ぶ。こうすると import httpx の行に赤い下線が出なくなる

期待される出力（httpx のバージョンは、みなさんの場合もっと新しいかもしれません）：

Python      : 3.12
In a venv   : True
Env folder  : .venv
httpx       : 0.28.1
Client ready: True
Hello, AI engineer.

それから、わざと壊してみてください。uv remove httpx を実行してから、もう一度 uv run env_check.py を実行します。どこまで表示されたか、どのエラーが出たか、そして pyproject.toml の何が変わったかを書き留めてください。それから uv add httpx で直します。この「壊して直す」のサイクルは 2 分しかかかりませんが、最初の仕事の最初の 1 週間で、いちばん多くの時間を節約してくれるものになるでしょう。