初めてのuv入門|uvコマンドガイド:uv Python versions編
知識は武器とかけまして、レゴブロックと解く、その心は――
今日もKnowledge Oasisへようこそ
案内人はkoふみです
本日のテーマは『uv python コマンドガイド』
対象読者
この記事は、Python をプロジェクト単位で柔軟に管理したいエンジニアや開発者の方を想定しています。
特に、複数の Python バージョンを使い分ける必要がある方や、コマンドラインツールで手軽に環境構築を行いたい方に役立つ内容です。
uv python
を使ったバージョン管理をすぐに実践したい方にぴったりです。
uv python install:Python環境を導入
概要
uv が管理する Python を自動でダウンロードしてインストールします。システムに Python がなくても、最新サポート中バージョンを手間なく取得できるのがポイントです。
使い方
uv python install
- 引数なし → 最新のサポート中 Python(例:3.x 系最新)を取得です。
- プロジェクトに
.python-versions
があれば、その中身に従って一括インストールも可能です。
主なオプション
- バージョン指定
uv python install 3.12 # 3.12 系最新パッチ
uv python install 3.12.3 # 3.12.3 をピンポイントで取得
- 複数同時インストール
uv python install 3.9 3.10 3.11
→ 3.9.x、3.10.x、3.11.x の最新パッチを一度に取得します。
- 再インストール
uv python install --reinstall
→ 配布元で修正があった場合などに、同じバージョン番号でも再取得して上書き可能。
ポイント
- インストール後、グローバル PATH には載らないため、
uv run python
や仮想環境内で利用してください。 - 新しいマイナーバージョン(例:3.13)が追加されたときは、uv 本体をアップデートしてからインストールを行います。
uv python list:利用可能なPythonを一覧表示
概要
システムにインストール済みの Python と、uv がダウンロード可能な最新パッチ候補をまとめて表示します。
使い方
uv python list
- インストール済みバージョン+各メジャーの最新パッチを一覧表示します。
主なオプション
--only-installed
uv python list --only-installed
→ インストール済みバージョンのみ表示します。
--only-downloads
uv python list --only-downloads
→ ダウンロード候補のみ表示(インストール済みは省略)します。
--all-versions
uv python list --all-versions
→ 各マイナー版のすべてのパッチ(古いもの含む)を表示します。
ポイント
-
オフライン表示:
--offline
オプションを使えば、ネットワークを使わずにキャッシュ済み情報だけで一覧可能。 - 「インストール済み×ダウンロード候補」を切り替えたい場合は、
--only-installed
/--only-downloads
を組み合わせて使うと便利です。
uv python find:実行可能なPythonを検出
概要
仮想環境やシステムにある Python 実行ファイルを検索し、最初に見つかったパスを返します。プロジェクト単位の仮想環境を優先的に検出します。
使い方
uv python find
-
.venv
があればその中のpython
を最優先で出力します。 - なければ PATH 上の
python3
→python
→python.exe
を順に探します。
主なオプション
- バージョン指定
uv python find '>=3.11'
→ バージョン 3.11 以上の実行ファイルを順に検索し、最初にマッチしたものを返します。
--system
uv python find --system
→ 仮想環境を無視して、システムにインストールされた Python のみを検索対象にします。
ポイント
-
VIRTUAL_ENV
環境変数が設定されていると、そちらの仮想環境を優先検出します。 - プロジェクト内で複数の仮想環境がある場合、カレントディレクトリ→親ディレクトリ…の順で
.venv
を探します。
uv python pin:デフォルトPythonバージョンを固定
概要
カレントディレクトリ(または親ディレクトリ)に .python-version
ファイルを生成し、以降その階層で uv コマンドを実行するときのデフォルトバージョンを固定します。
使い方
uv python pin 3.11.6
- 例:カレント以下の階層で
.python-version
を作成し、中身に3.11.6
を書き込みます。 - 以降、そのディレクトリ階層で
uv run
やuv python install
を実行するときは、3.11.6
をデフォルト要求として扱います。
グローバル設定
uv python pin --global 3.11.6
- ユーザー設定フォルダ(XDG 規約に従う場所)に
.python-version
を作成し、システム全体でデフォルトバージョンを3.11.6
に固定します。
主なオプション
-
--global
→ ユーザーレベルに.python-version
を作成し、どのプロジェクトでも同じバージョンをデフォルトにします。 --no-config
uv python pin 3.11.6 --no-config
→ カレント〜上位の .python-version
や設定ファイルを一切参照せず、手動指定バージョンを強制的に書き込みます。
ポイント
- 探索順序は「カレント→親→…→ユーザーレベル」。既に上位に
.python-version
がある場合はそこを上書きします。 - プロジェクト境界(
pyproject.toml
がある場所)を越えると探索は止まりますが、ユーザーレベル設定だけは例外的に検出されます。
uv python uninstall:不要なPythonを削除
概要
uv が管理下でインストールした Python バージョンをアンインストールします。システムに元からある Python は対象外です。
使い方
uv python uninstall 3.12.3
- 引数にバージョン(例:
3.12.3
)や制約(例:'>=3.8,<3.10'
)を指定すると、合致する管理下 Python を削除します。
主なオプション
--all
uv python uninstall --all
→ uv 管理下すべての Python バージョンを一括削除します。
--install-dir
(-i
)
uv python uninstall 3.10.4 --install-dir /path/to/dir
→ カスタムディレクトリにある管理下 Python のみを指定して削除します。
--offline
uv python uninstall 3.10.2 --offline
→ ネットワーク接続なしで、キャッシュ済み情報だけを参照してアンインストールします。
ポイント
-
誤削除を防ぐため、普段は
--managed-python
(デフォルト)だけで絞り込んで操作することをおすすめします。 - CI 環境などでネットワークを使いたくないときは
--offline
、出力を抑えたいときは--quiet
も併用すると便利です。
本記事では、プロジェクト単位で Python 環境を自在に扱うための uv python の5つのコマンドをご紹介しました。バージョンのインストールからリスト表示、実行ファイルの検出、バージョン固定、不要なバージョンの削除まで、日々の作業を効率化する要点をまとめたので、すぐに実践していただけるはずです。
知識のひとつひとつは小さなレゴブロック
でも、組み合わせれば世界を変えるアイディアをカタチにする武器になる!
またKnowledge Oasisでお会いしましょう
案内人はkoふみでした
Discussion