KGWORKS.NET
個人開発

uvでPythonのバージョンを管理する方法

更新

個人でスクリプトや小さなツールを書くとき、Pythonのバージョンが環境ごとにバラバラになりやすいです。uv を使うと「Python本体の導入」と「プロジェクトの固定」までまとめて扱えます。

この記事では、バージョン管理に絞って手順を解説します。（2026年9月時点）あわせて、uvを使わずにPythonを入れた場合との違いと、Cursor / VS Code で .venv を選ぶ方法も記載します。

uvとは

uv は Astral 製の Python 向けツールです。依存関係の解決が速いイメージが強いですが、管理された Python（managed Python）を自分で入れたり、プロジェクトにピン留めしたりもできます。

uvを使わずに入れた場合との比較

よくある「uvなし」の入れ方は次のようなものです。

  • python.org の公式インストーラ
  • macOS の Homebrew（brew install python）
  • Windows の Microsoft Store / 公式インストーラ
  • pyenv で複数バージョンを切り替え

それぞれ単体でも問題なく使えます。違いが出るのは「複数バージョン」「プロジェクトごとの固定」「再現性」です。

観点 uvなし（公式 / brew など） uvあり
入れるもの OSや公式の Python 本体 uv が managed Python も管理できる
複数バージョン 自分でパスやツールを分ける必要が出やすい uv python install 3.12 3.13 で並べやすい
プロジェクト固定 手動、または pyenv local など別ツール uv python pin → .python-version
仮想環境 python -m venv を自分で作る uv venv / uv sync / uv run が一体
向いている人 1バージョンだけで十分な人 プロジェクトごとに利用するPythonのバージョンを明確に分けたい人
ざっくり言うと： 1台のマシンで簡単なスクリプトを書いて実行させるくらいなら公式や Homebrew 経由のインストールでも十分です。
プロジェクトごとに Python を揃えたいなら uvの方が運用・保守が圧倒的に楽です。
というのもPythonで使うライブラリはPythonのバージョンに依存しますし、pipも同様にバージョン依存するため、プロジェクトごとに分けておくと「以前作ったものが動かなくなった」というトラブルが減ります。

1. 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

standalone で入れた場合の更新:

uv self update

2. Python本体をインストールする

uv python install 3.12

複数まとめて:

uv python install 3.12 3.13

一覧:

uv python list
  • 必要なときに自動取得されることもある
  • 明示的に install しておくと再現しやすい
  • 入るのは Astral 側配布（python-build-standalone）ベースの managed Python
  • システムの Python も使える。managed だけに寄せたいときは --managed-python を検討

3. プロジェクトのバージョンを固定する

uv python pin 3.12

.python-version が作られ（または更新され）、そのディレクトリでは 3.12 系が基準になります。Git に含めると別マシンでも揃えやすいです。

新規プロジェクト例:

uv init myapp
cd myapp
uv python pin 3.12
uv venv --python 3.12

4. 日常の使い方（最小セット）

uv run python --version
uv run --python 3.13 python --version

グローバル切替より、ディレクトリの .python-version で固定する方がトラブルが少ないです。

5. Cursor / VS Code でインタプリタを .venv に向ける

uv で仮想環境を作ると、だいたいプロジェクト直下に .venv ができます。エディタ側でこれを選ばないと、補完や実行がシステムの別 Python を見ることがあります。

  1. ターミナルでプロジェクトに入り、環境を作る（まだなら）
uv venv --python 3.12
# 依存があるプロジェクトなら
uv sync
  1. Cursor または VS Code でそのフォルダを開く
  2. コマンドパレットを開く（macOS なら Cmd+Shift+P、Windows なら Ctrl+Shift+P）
  3. Python: Select Interpreter を選ぶ
  4. 一覧から ./.venv/bin/python（macOS / Linux）または .\.venv\Scripts\python.exe（Windows）を選ぶ
  5. 右下ステータスバーの Python 表示が .venv になっているか確認

出てこないとき:

  • コマンドパレットで Python: Refresh Interpreters
  • それでも無ければ「Enter interpreter path...」で .venv 内の python を直接指定
  • フォルダを開き直す（ルートがプロジェクト直下か確認）

ターミナルでも揃えるなら:

# macOS / Linux
source .venv/bin/activate

# Windows (PowerShell)
.\.venv\Scripts\Activate.ps1
日常の実行は uv run ... でもよく、エディタのインタプリタ選択は主に補完・デバッグ・Run Python File 用、と分けると混乱しにくいです。

6. pyenvユーザー向けの対応表

やりたいこと pyenvっぽい操作 uv
本体を入れる pyenv install 3.12.x uv python install 3.12
一覧 pyenv versions uv python list
このディレクトリで固定 pyenv local 3.12.x uv python pin 3.12
その Python で動かす python / pyenv exec uv run

7. よくあるつまずき

  • 入れたのに古い Python が使われる → .python-version と uv run python --version を確認。エディタが別インタプリタを指していないかも見る
  • CIや別PCで違う → .python-version をリポジトリに含める
  • 新しいマイナーが install に出ない → 先に uv self update
  • エディタだけ古い → Python: Select Interpreter で .venv を選び直す

まとめ

  1. 公式や brew だけでも動く。複数プロジェクトでの運用や別マシンでの再現性を重視するなら uv が楽
  2. uv を入れる → uv python install 3.12 → uv python pin 3.12
  3. 実行は uv run、エディタは .venv を Select Interpreter で指定

個人プロジェクトでも、これだけで「PCを変えたら動かない」「勝手にライブラリバージョンが変わって使えなくなった」「エディタだけ別Python」がかなり減ります。