Pythonバージョン
Pythonバージョンは、Pythonインタープリタ（つまり、python実行ファイル）、標準ライブラリ、およびその他のサポートファイルで構成されます。
管理されたPythonインストールとシステムPythonインストール
システムに既存のPythonインストールがあることが一般的であるため、uvはPythonバージョンの検出をサポートしています。ただし、uvはPythonバージョンを自分でインストールすることもサポートしています。これらの2つのタイプのPythonインストールを区別するために、uvは自分でインストールしたPythonバージョンを_管理された_ Pythonインストールと呼び、その他のすべてのPythonインストールを_システム_ Pythonインストールと呼びます。
Note
uvは、オペレーティングシステムによってインストールされたPythonバージョンと他のツールによってインストールおよび管理されたPythonバージョンを区別しません。たとえば、Pythonインストールがpyenvで管理されている場合でも、uvでは_システム_ Pythonバージョンと見なされます。
バージョンのリクエスト
特定のPythonバージョンは、ほとんどのuvコマンドで--pythonフラグを使用してリクエストできます。たとえば、仮想環境を作成する場合：
uvはPython 3.11.6が利用可能であることを確認し、必要に応じてダウンロードおよびインストールし、そのバージョンで仮想環境を作成します。
次のPythonバージョンリクエスト形式がサポートされています：
<version>例：3、3.12、3.12.3<version-specifier>例：>=3.12,<3.13<implementation>例：cpythonまたはcp<implementation>@<version>例：cpython@3.12<implementation><version>例：cpython3.12またはcp312<implementation><version-specifier>例：cpython>=3.12,<3.13<implementation>-<version>-<os>-<arch>-<libc>例：cpython-3.12.3-macos-aarch64-none
さらに、特定のシステムPythonインタープリタを次の形式でリクエストできます：
<executable-path>例：/opt/homebrew/bin/python3<executable-name>例：mypython3<install-dir>例：/some/environment/
デフォルトでは、uvはシステム上で見つからない場合にPythonバージョンを自動的にダウンロードします。この動作はpython-downloadsオプションで無効にできます。
Pythonバージョンファイル
.python-version ファイルは、デフォルトのPythonバージョンリクエストを作成するために使用できます。uv は作業ディレクトリおよびその親ディレクトリに .python-version ファイルを検索します。上記で説明したリクエスト形式のいずれも使用できますが、他のツールとの互換性のためにバージョン番号の使用が推奨されます。
.python-version ファイルは、uv python pin コマンドを使用して現在のディレクトリに作成できます。
.python-version ファイルの検出は、--no-config オプションで無効にできます。
uv はプロジェクトまたはワークスペースの境界を超えて .python-version ファイルを検索しません。
Pythonバージョンのインストール
uvはmacOS、Linux、およびWindows向けのダウンロード可能なCPythonおよびPyPyディストリビューションのリストをバンドルしています。
Tip
デフォルトでは、Pythonバージョンはuv python installを使用せずに必要に応じて自動的にダウンロードされます。
特定のバージョンのPythonバージョンをインストールするには：
最新のパッチバージョンをインストールするには：
制約を満たすバージョンをインストールするには：
複数のバージョンをインストールするには：
特定の実装をインストールするには：
すべての Python バージョンリクエスト 形式がサポートされていますが、ファイルパスなどのローカルインタープリタをリクエストするために使用される形式は除きます。
デフォルトでは、uv python install は管理された Python バージョンがインストールされていることを確認するか、最新バージョンをインストールします。.python-version ファイルが存在する場合、uv はファイルに記載されている Python バージョンをインストールします。複数の Python バージョンを必要とするプロジェクトは、.python-versions ファイルを定義することができます。存在する場合、uv はファイルに記載されているすべての Python バージョンをインストールします。
プロジェクトの Python バージョン
uv は、プロジェクトコマンドの呼び出し中に pyproject.toml ファイルの requires-python に定義された Python 要件を尊重します。要件に適合する最初の Python バージョンが使用されますが、.python-version ファイルや --python フラグを介してバージョンが要求されている場合はその限りではありません。
利用可能なPythonバージョンの表示
インストール済みおよび利用可能なPythonバージョンを一覧表示するには：
デフォルトでは、他のプラットフォームおよび古いパッチバージョンのダウンロードは非表示になります。
すべてのバージョンを表示するには：
他のプラットフォームのPythonバージョンを表示するには：
ダウンロードを除外し、インストール済みのPythonバージョンのみを表示するには：
Python実行ファイルの検索
Python実行ファイルを検索するには、uv python findコマンドを使用します：
デフォルトでは、最初に利用可能なPython実行ファイルのパスが表示されます。実行ファイルがどのように検出されるかの詳細については、検出ルールを参照してください。
このインターフェースは多くのリクエスト形式もサポートしています。たとえば、3.11以上のバージョンを持つPython実行ファイルを検索するには：
デフォルトでは、uv python findは仮想環境からのPythonバージョンを含めます。作業ディレクトリまたは親ディレクトリのいずれかに.venvディレクトリが見つかるか、VIRTUAL_ENV環境変数が設定されている場合、それはPATH上の他のPython実行ファイルよりも優先されます。
仮想環境を無視するには、--systemフラグを使用します：
Pythonバージョンの検出
Pythonバージョンを検索する場合、次の場所がチェックされます：
UV_PYTHON_INSTALL_DIRにある管理されたPythonインストール。PATH上のpython、python3、またはpython3.xとしてのPythonインタープリタ（macOSおよびLinuxの場合）またはpython.exe（Windowsの場合）。- Windowsでは、Windowsレジストリ内のPythonインタープリタおよびMicrosoft StoreのPythonインタープリタ（
py --list-pathsを参照）がリクエストされたバージョンに一致します。
一部のケースでは、uvは仮想環境からのPythonバージョンの使用を許可します。この場合、仮想環境のインタープリタはリクエストとの互換性があるかどうかを確認し、上記のようにインストールを検索する前にチェックされます。詳細については、pip互換の仮想環境の検出のドキュメントを参照してください。
検出を行う際、実行可能でないファイルは無視されます。検出された各実行ファイルはメタデータを照会して、リクエストされたPythonバージョンを満たしていることを確認します。照会が失敗した場合、実行ファイルはスキップされます。実行ファイルがリクエストを満たす場合、追加の実行ファイルを検査せずに使用されます。
管理されたPythonバージョンを検索する場合、uvは新しいバージョンを優先します。システムPythonバージョンを検索する場合、uvは最も新しいバージョンではなく、最初に互換性のあるバージョンを使用します。
システム上でPythonバージョンが見つからない場合、uvは互換性のある管理されたPythonバージョンのダウンロードを確認します。
Pythonプレリリース
デフォルトでは、Pythonプレリリースは選択されません。Pythonプレリリースは、リクエストに一致する他のインストールがない場合に使用されます。たとえば、プレリリースバージョンのみが利用可能な場合、それが使用されますが、通常は安定リリースバージョンが使用されます。同様に、プレリリースのPython実行ファイルのパスが提供された場合、他のPythonバージョンがリクエストに一致しないため、プレリリースバージョンが使用されます。
プレリリースのPythonバージョンが利用可能でリクエストに一致する場合、uvは代わりに安定したPythonバージョンをダウンロードしません。
自動Pythonダウンロードの無効化
デフォルトでは、uvは必要に応じてPythonバージョンを自動的にダウンロードします。
python-downloadsオプションを使用してこの動作を無効にできます。デフォルトではautomaticに設定されていますが、manualに設定すると、uv python install中にのみPythonのダウンロードが許可されます。
Tip
python-downloads設定は、デフォルトの動作を変更するために永続的な構成ファイルに設定できます。また、任意のuvコマンドに--no-python-downloadsフラグを渡すこともできます。
Pythonバージョンの優先順位の調整
デフォルトでは、uvはシステム上で見つかったPythonバージョンを使用し、必要に応じて管理されたインタープリタをダウンロードします。
python-preferenceオプションを使用してこの動作を調整できます。デフォルトではmanagedに設定されており、システムPythonインストールよりも管理されたPythonインストールを優先します。ただし、システムPythonインストールは管理されたPythonバージョンのダウンロードよりも優先されます。
次の代替オプションが利用可能です：
only-managed: 管理されたPythonインストールのみを使用し、システムPythonインストールは使用しないsystem: システムPythonインストールを管理されたPythonインストールよりも優先するonly-system: システムPythonインストールのみを使用し、管理されたPythonインストールは使用しない
これらのオプションにより、uvの管理されたPythonバージョンを完全に無効にするか、常にそれらを使用し、既存のシステムインストールを無視することができます。
Note
Pythonバージョンの自動ダウンロードは、優先順位を変更せずに無効にすることができます。
Python実装のサポート
uvはCPython、PyPy、およびGraalPyのPython実装をサポートしています。Python実装がサポートされていない場合、uvはそのインタープリタを検出できません。
実装は長い名前または短い名前のいずれかでリクエストできます：
- CPython:
cpython、cp - PyPy:
pypy、pp - GraalPy:
graalpy、gp
実装名のリクエストは大文字と小文字を区別しません。
サポートされている形式の詳細については、Pythonバージョンリクエストのドキュメントを参照してください。
管理されたPythonディストリビューション
uvはCPythonおよびPyPyディストリビューションのダウンロードとインストールをサポートしています。
CPythonディストリビューション
Pythonは公式の配布可能なCPythonバイナリを公開していないため、uvは代わりにpython-build-standaloneプロジェクトからの事前構築されたサードパーティディストリビューションを使用します。python-build-standaloneは部分的にuvのメンテナによって維持されており、Ryeやbazelbuild/rules_pythonなどの他の多くのPythonプロジェクトで使用されています。
uvのPythonディストリビューションは自己完結型で、高い移植性とパフォーマンスを備えています。Pythonをソースからビルドすることもできますが、pyenvなどのツールで行う場合、事前にシステム依存関係が必要であり、最適化されたパフォーマンスの高いビルド（例：PGOおよびLTOが有効）を作成するには非常に時間がかかります。
これらのディストリビューションには、一般的に移植性の結果としていくつかの動作の癖があります。現在、uvはAlpine LinuxのようなmuslベースのLinuxディストリビューションへのインストールをサポートしていません。詳細については、python-build-standaloneの癖のドキュメントを参照してください。
PyPyディストリビューション
PyPyディストリビューションはPyPyプロジェクトによって提供されています。