uv-python-versions

UV Python バージョン管理

UV を使用した Python インタープリターのバージョンのインストールと管理に関するクイックリファレンスです。

このスキルを使用する場合

次の場合にこのスキルを使用します…	代わりに、用途に特化した関連スキルを使用します…
uv python install で特定の CPython または PyPy インタープリターをインストールする	プロジェクトに Python ライブラリを追加する場合 — uv-project-management を使用します
.python-version または requires-python でプロジェクトの Python バージョンを固定する	グローバルな Python CLI ツールをインストールする場合 — uv-tool-management を使用します
テスト用に、インストール済みの複数のインタープリターを切り替える	Python を自動管理してスクリプトを実行する場合 — uv-run を使用します

このスキルが適用される場合

• 特定の Python バージョンをインストールする
• 複数の Python バージョンを切り替える
• プロジェクトの Python バージョンを固定する
• CPython および PyPy インタープリターを管理する
• インストール済みの Python バージョンを検索・一覧表示する

クイックリファレンス

Python バージョンのインストール

# Install latest Python
uv python install

# Install specific version
uv python install 3.11
uv python install 3.12
uv python install 3.10 3.11 3.12

# Install exact version
uv python install 3.11.5
uv python install [email protected]

# Install PyPy
uv python install [email protected]
uv python install [email protected]

Python バージョンの一覧表示

# List all available versions
uv python list

# List only installed versions
uv python list --only-installed

# List with verbose details
uv python list --verbose

Python バージョンの固定

# Pin version for current project
uv python pin 3.11
uv python pin 3.12.1

# Pin PyPy
uv python pin [email protected]

# Pin with version file
# Creates/updates .python-version

Python インタープリターの検索

# Find any Python installation
uv python find

# Find specific version
uv python find 3.11
uv python find 3.12

# Find PyPy
uv python find pypy
uv python find [email protected]

特定の Python バージョンの使用

# In project commands
uv run --python 3.11 script.py
uv run --python 3.12 pytest

# Creating virtual environments
uv venv --python 3.11
uv venv --python 3.10 .venv-py310

# Initializing projects
uv init --python 3.12 my-project

Python バージョンの取得元

UV は次の順序で Python を検索します。

1. UV 管理対象 - uv python install でインストールされたもの
2. .python-version - プロジェクトディレクトリ内の固定ファイル
3. pyproject.toml - requires-python フィールド
4. システム Python - 既存のシステムインストール
5. 環境 - $PATH および標準の場所

バージョンの固定

.python-version ファイル

# Pin creates this file
uv python pin 3.11

# File contents
3.11

# Exact version
uv python pin 3.11.5

pyproject.toml

[project]
requires-python = ">=3.11"

# UV respects this constraint

サポート対象の Python 実装

CPython

# Default implementation
uv python install 3.11
uv python install [email protected]
uv python install [email protected]

PyPy

# Alternative Python implementation
uv python install [email protected]
uv python install [email protected]

よく使うコマンド

# Install and pin latest Python 3.12
uv python install 3.12 && uv python pin 3.12

# Install multiple versions for testing
uv python install 3.10 3.11 3.12

# Check which Python is active
uv python find
uv run python --version

# Uninstall version (manual)
rm -rf ~/.local/share/uv/python/cpython-3.11.5-*

プロジェクトとの連携

プロジェクトの初期化

# Initialize with specific Python
uv init --python 3.11 my-project

# Generates .python-version
cat .python-version
# 3.11

コマンドの実行

# Use project's pinned Python
uv run python script.py

# Override with specific version
uv run --python 3.12 script.py

# Use system Python
uv run --python python3 script.py

複数バージョンでのテスト

# Test across Python versions
uv run --python 3.10 pytest
uv run --python 3.11 pytest
uv run --python 3.12 pytest

# Create version-specific venvs
uv venv --python 3.10 .venv-py310
uv venv --python 3.11 .venv-py311
uv venv --python 3.12 .venv-py312

主な機能

• 高速なダウンロード：キャッシュを利用した並列ダウンロード
• 自動化：必要に応じてバージョンをダウンロード
• 分離：UV 管理対象のバージョンはシステム Python と競合しません
• ポータブル：スタンドアロンの Python ディストリビューションを使用
• クロスプラットフォーム：Linux、macOS、Windows で動作します

関連項目

• uv-project-management - プロジェクトで固定済みの Python バージョンを使用する
• uv-workspaces - モノレポでの Python バージョン
• python-testing - 複数の Python バージョンにまたがるテスト

参考資料

• 公式ドキュメント：https://docs.astral.sh/uv/guides/install-python/
• Python スタンドアロンビルド：https://github.com/indygreg/python-build-standalone
• 詳細ガイド：このスキルディレクトリ内の REFERENCE.md を参照してください