Python の環境構築、毎回ちょっとだけ憂鬱じゃないですか？
pyenv で Python のバージョンを入れて、venv で仮想環境を切って、依存は pip か poetry で…と、
ツールがバラバラだと「あれ、このプロジェクトどうやって作ったんだっけ」と毎回思い出す羽目になります。 自分もずっとそうでした。
それが uv に一本化したら、環境構築から Python のバージョン管理、依存、ツール導入まで、 ぜんぶ uv ひとつで片付くようになりました。
今回はその「環境構築」と「バージョン管理」のところを、 自分が使っているコマンド中心にまとめてみます。
uv とは(ざっくり)
uv は Astral 製の、Python のオールインワン管理ツールです。
- 仮想環境(venv 相当)
- 依存関係・パッケージ管理(pip / poetry 相当)
- Python 本体のバージョン管理(pyenv 相当)
- CLI ツールの導入(pipx 相当)
これらを1つにまとめてくれて、しかも爆速。「pip も venv も pyenv も poetry も」だったものが、 uv だけ覚えればいい状態になります。
インストールは Mac / Linux なら curl 一発です。
curl -LsSf https://astral.sh/uv/install.sh | sh uv self version # バージョン確認
1. 環境構築:プロジェクトを作る
新しいプロジェクトはこれだけです。
uv init my_project # プロジェクト雛形を作成 cd my_project uv add pandas matplotlib # 依存を追加(pyproject.toml に書き込まれる)
uv add すると pyproject.toml の dependencies に追記され、同時に uv.lock も更新されます。
仮想環境(.venv)は uv が勝手に作って勝手に使ってくれる ので、source .venv/bin/activate を
打つ必要すらありません。実行はこう。
uv run python main.py # .venv 経由で実行してくれる uv run pytest # テストもこれでOK
依存まわりで自分がよく使うのはこのあたりです。
| コマンド | 何をする |
|---|---|
uv add <pkg> |
依存を追加 |
uv remove <pkg> |
依存を削除 |
uv lock |
ロックファイル(uv.lock)を更新 |
uv sync |
ロックに合わせて .venv を同期 |
uv tree |
依存ツリーを確認 |
2. Python本体のバージョン管理
ここが地味に大事なところ。uv は Python 本体も管理できます。
uv python install 3.11 3.12 3.13 # 複数バージョンを入れられる uv python list # 入っているもの一覧
そして、プロジェクトごとに使う Python を固定するのが uv python pin です。
uv python pin 3.13 # → Updated `.python-version` from `3.11` -> `3.13`
これで .python-version というファイルが作られ、uv はこのプロジェクトでは常に 3.13 を使ってくれます。
.python-version と requires-python は別物
最初ここで混乱しがちなので整理しておきます。
| 書く場所 | 役割 |
|---|---|
.python-version |
開発環境でどの Python を使うか(自分の手元の固定) |
pyproject.toml の requires-python |
パッケージのメタdataとして、対応する Python の範囲 |
手元で動かす版を決めるのが .python-version、配布物として「3.11以上対応です」と宣言するのが
requires-python、という住み分けです。
ハマりどころ: pin したのに思ったPython バージョンにならない
自分が最初にハマったのが「pin した覚えのない 3.11 になっている」現象でした。
これは uv python pin 3.12 のように マイナーまでしか指定しない(loose)と、
手元にある最新の 3.12.x が使われるためです。
パッチまでカチッと固定したいなら、フルバージョンで pin します。
uv python pin 3.12.7 # パッチまで固定 uv lock # 制約に合わせて依存を再解決 uv sync # .venv をその版で作り直してくれる
uv sync は、インタプリタが変わると .venv を勝手に作り直してくれるので、
仮想環境を手で消して作り直す必要はありません。ここが地味にラクです。
3. プロジェクトの「バージョン」を管理する(セマンティックバージョニング)
Python の版だけでなく、自分のプロジェクト自身のバージョン(1.2.3 みたいなやつ)も uv で扱えます。
uv version # 今のバージョンを表示 uv version --bump patch # 1.2.3 -> 1.2.4 uv version --bump minor # 1.2.3 -> 1.3.0 uv version --bump major # 1.2.3 -> 2.0.0
uv version --bump は pyproject.toml の version 文字列を直接書き換えるので、
pyproject.toml が常に「正」 になります。あとはこれを git tag と組み合わせて、
- コミット単位の小さな変更 → build / patch を上げる
- 機能追加 → minor を上げる
- 大きな構造変更 → major を上げる
というルールで運用し、bump したらタグを切る、という流れにすると管理がブレません。 簡単な bash スクリプトにまとめれば、bump → changelog → git tag → push まで一発にできます。
4. CI / Docker でも「同じ版」を使う
手元と CI とで Python の版がズレると、ローカルで通ったのに CI で落ちる、という事故が起きます。
uv なら .python-version を共通の真実にして揃えられます。
- GitHub Actions:
astral-sh/setup-uvで uv を入れて、uv syncでピン留めされた版を入れる - Docker:
uv syncの前に.python-versionをイメージにコピーしておく
これで「ローカルと CI と本番が同じ Python で動く」状態になります。 環境はなるべく統一して、毎回悩まないようにしておくと、後がずっとラクです。
まとめ
uv に寄せてよかったのは、結局これに尽きます。
- 環境構築:
uv init→uv add→uv run。.venvは uv が面倒を見る - Pythonの版:
uv python install/uv python pin(loose と exact を使い分ける) - プロジェクトの版:
uv version --bumpで pyproject.toml を正にして semver 運用 - CI/Docker:
.python-versionを共通の真実にして全環境を揃える
道具がバラバラだと環境構築のたびに悩みますが、uv に統一すると「毎回同じやり方」で再現性が上がります。 新しいマシンでも、新しいプロジェクトでも、同じ手順で立ち上がる。これがいちばんの時短だと思います。
ではでは。
