Skip to content

Python versions#

Pythonバージョンは、Pythonインタプリタ(つまりpython実行可能ファイル)、標準ライブラリ、その他のサポートファイルで構成されています。

Managed and system Python installations#

システムに既存のPythonがインストールされていることは一般的であるため、uvはdiscoveringPythonバージョンをサポートします。ただし、uvはinstalling Python versions自体もサポートします。これら2つのタイプのPythonインストールを区別するために、uvは_managed_PythonインストールとしてインストールされるPythonバージョンと、_system_Pythonインストールとしてインストールされる他のすべてのPythonバージョンを参照します。

Note

uvは、オペレーティングシステムによってインストールされたPythonバージョンと、他のツールによってインストールおよび管理されているPythonバージョンを区別しません。たとえば、Pythonインストールがpyenvで管理されている場合、uvでは_system_Pythonバージョンと見なされます。

Requesting a version#

ほとんどのuvコマンドでは、--pythonフラグを使用して特定のPythonバージョンを要求できます。たとえば、仮想環境を作成する場合は、次のようになります。

$ uv venv --python 3.11.6

uvは、Python 3.11.6が利用可能であることを確認し(必要に応じてダウンロードしてインストールし)、それを使用して仮想環境を作成します

次のPythonバージョンをリクエストするためのフォーマットがサポートされています。

  • <version> 例: 3, 3.12, 3.12.3
  • <version-specifier> 例: >=3.12,<3.13
  • <implementation> 例: cpython or cp
  • <implementation>@<version> 例: cpython@3.12
  • <implementation><version> 例: cpython3.12 or cp312
  • <implementation><version-specifier> 例: cpython>=3.12,<3.13
  • <implementation>-<version>-<os>-<arch>-<libc> 例: cpython-3.12.3-macos-aarch64-none

さらに、特定のシステムPythonインタプリタを次のように要求することもできます。:

  • <executable-path> e.g. /opt/homebrew/bin/python3
  • <executable-name> e.g. mypython3
  • <install-dir> e.g. /some/environment/

デフォルトでは、システム上にPythonバージョンが見つからない場合、uvは自動的にダウンロードします。この動作は、python-downloadsオプションで無効にすることができます。

Installing a Python version#

uvには、macOS、Linux、Windows用のダウンロード可能なCPythonおよびPyPyディストリビューションのリストがバンドルされています。

Tip

デフォルトでは、Pythonバージョンはuv python installを使用せずに必要に応じて自動的にダウンロードされます。

Pythonバージョンを特定のバージョンにインストールするには:

$ uv python install 3.12.3

最新のパッチ・バージョンをインストールするには:

$ uv python install 3.12

制約を満たすバージョンをインストールするには:

$ uv python install '>=3.8,<3.10'

複数のバージョンをインストールするには:

$ uv python install 3.9 3.10 3.11

特定の実装をインストールするには:

$ uv python install pypy

ファイルパスなどのローカルインタプリタの要求に使用される形式を除き、すべてのPython version request形式がサポートされています。

Project Python versions#

デフォルトでは、uv python installは管理されたPythonバージョンがインストールされていることを確認するか、最新バージョンをインストールします。

あるいは、複数のPythonバージョンを必要とするプロジェクトで.python-versionsファイルを定義することもできます。存在する場合、uvは

あるいは、複数のPythonバージョンを必要とするプロジェクトで.python-versionsファイルを定義することもできます。存在する場合、uvはファイルにリストされているすべてのPythonバージョンをインストールします。このファイルは.python-versionファイルよりも優先されます。

uvは、プロジェクトコマンドの呼び出し時にpyproject.tomlファイルで定義されたPythonの要件も考慮します。

Viewing available Python versions#

インストールされているPythonバージョンと使用可能なPythonバージョンをリストするには:

$ uv python list

デフォルトでは、他のプラットフォームや古いパッチバージョンのダウンロードは表示されません。

すべてのバージョンを表示するには:

$ uv python list --all-versions

他のプラットフォームのPythonバージョンを表示するには:

$ uv python list --all-platforms

ダウンロードを除外し、インストールされているPythonバージョンのみを表示するには:

$ uv python list --only-installed

Discovery of Python versions#

Pythonバージョンを検索する場合、次の場所がチェックされます。:

-UV_PYTHON_INSTALL_DIRでPythonのインストールを管理します。 - python、python3、またはpython3.x(macOSとLinuxの場合)、またはpython.exe(Windowsの場合)としてPATH上のPythonインタプリタ。 - Windowsでは、要求されたバージョンに一致するpy--list-pathsによって返されるPythonインタプリタ。

場合によっては、uvによって仮想環境からPythonバージョンを使用できるようになります。この場合、前述のように、インストールを検索する前に、仮想環境のインタプリタが要求との互換性をチェックされます。詳細については、pip-compatible virtual environment discoveryのドキュメントを参照してください。

検出を実行する場合、実行可能でないファイルは無視されます。検出された各実行可能ファイルは、requested Python versionを満たすことを確認するためにメタデータが照会されます。照会が失敗した場合、実行可能ファイルはスキップされます。実行可能ファイルが要求を満たす場合、追加の実行可能ファイルを検査せずに使用されます。

マネージドPythonバージョンを検索する場合、uvは新しいバージョンを優先します。システムPythonバージョンを検索する場合、uvは最新バージョンではなく、最初の互換性のあるバージョンを使用します。

システム上にPythonのバージョンが見つからない場合、uvは互換性のある管理されたPythonバージョンのダウンロードをチェックします。

Disabling automatic Python downloads#

デフォルトでは、uvは必要に応じて自動的にPythonバージョンをダウンロードします。

python-downloadsオプションを使用して、この動作を無効にすることができます。デフォルトではautomaticに設定されていますが、uv python install中にPythonのダウンロードのみを許可するにはmanualに設定します。

Adjusting Python version preferences#

デフォルトでは、uvはシステム上にあるPythonバージョンの使用を試み、必要な場合にのみ管理対象インタプリタをダウンロードします。

python-preferenceオプションを使用して、この動作を調整できます。デフォルトではmanagedに設定されており、システムPythonインストールよりもマネージドPythonインストールが優先されます。ただし、システムPythonインストールの方が、マネージドPythonバージョンをダウンロードするよりも優先されます。

次の代替オプションを使用できます。

  • only-managed:管理されたPythonインストールのみを使用し、システムPythonインストールは使用しません。
  • system:管理されたPythonインストールよりもシステムPythonインストールを優先します。
  • only-system:システムPythonインストールのみを使用し、管理されたPythonインストールは使用しません。

これらのオプションを使用すると、uvのマネージドPythonバージョンを完全に無効にしたり、常に使用して既存のシステムインストールを無視したりすることができます。

Note

Pythonバージョンの自動ダウンロードは、プリファレンスを変更せずにdisabledにすることができます。

Python implementation support#

uvは、CPython、PyPy、およびGraalPyのPython実装をサポートしています。Python実装がサポートされていない場合、uvはインタプリタの検出に失敗します。

実装は、長い名前または短い名前のいずれかで要求できます。:

  • CPython: cpython, cp
  • PyPy: pypy, pp
  • GraalPy: graalpy, gp

実装名の要求では、大文字と小文字は区別されません。

See the Python version request documentation for more details on the

サポートされているフォーマットの詳細については、Python version requestのドキュメントを参照してください

Managed Python distributions#

uvは、CPythonおよびPyPyディストリビューションのダウンロードとインストールをサポートしています。

CPython distributions#

Pythonは公式に配布可能なCPythonバイナリを公開しておらず、uvはpython-build-standaloneプロジェクトからのサードパーティのスタンドアロンディストリビューションを使用しています。このプロジェクトは部分的にuvメンテナによって維持されており、他の多くのPythonプロジェクトでも使用されています。

uv Pythonディストリビューションは自己完結型で、移植性が高く、パフォーマンスに優れています。Pythonはpyenvのようなツールのようにソースから構築できますが、事前にインストールされたシステム依存関係を必要とし、最適化されたパフォーマンスの高いビルドを作成するのは非常に時間がかかります。

python-build-standalone quirks documentation for details.

これらのディストリビューションには、一般的に移植性の結果として、いくつかの動作上の癖があります。詳細については、python-build-standalone quirksのドキュメントを参照してください。

PyPy distributions#

PyPyディストリビューションはPyPyプロジェクトによって提供されています。