「Uv が使うpythonランタイム」の版間の差分

2026年11月5日 (木) 23:00時点における版

メインページ>コンピュータの部屋#Python>uv tips

はじめに

uv はパッケージ管理ツールであると共に pythonランタイムを管理する管理ツールでもあります。 この記事では uv がどのように pythonランタイムを管理するかを解説します。

uv の対象は Windows版 0.13.7 です。

尚この記事では Windows で uv を利用することを前提にします。 linux や Mac では検証していませんのであしからず。

用語

pythonランタイム

特定のバージョンのpython一式のことです。pythonインタープリターや標準ライブラリやいくつかのツールの詰め合わせです。

system python

uvが管理していない pythonランタイムです。

managed python

uvが管理している pythonランタイムです。

tomlファイル

正しい名称は pyproject.toml ファイル。プロジェクトの設定を保持するファイル

.python-version

プロジェクトが仮想環境で使用する pythonランタイムのバージョンを指定するファイル。pyproject.tomlに次いで重要な設定ファイル。

基本的なポリシー

uv は uv が管理している Pythonランタイムを自由にインストールすることができます。

uv は自分が管理している managed python の利用に固執しません。適当な system python が存在していれば それを使って仮想環境を作ることもできます。

system python と managed python の共存も可能ですが、 uv は managed python があれば system python より優先して仮想環境に利用します。

既定のpythonランタイムのバージョン

uvはプロジェクトを作成する際、既定の pythonバージョンを予め設定しておくことができます。 現在よく使う pythonバージョンを設定しておくと便利です。

uv python pin <pythonバージョン> --global
例: uv python pin 3.13 --global

既定値の設定では --global オプションを付けます。

uv は ~/AppSata/roaming/uv/.python-version に既定の pythonランタイムのバージョンを格納します。 ファイルの中身は 3.14 とか 3.15 とかがテキストで書かれています。

pythonランタイムバージョンは pythonが managed か system かを指定しないことに注意してください。 pythonランタイムバージョンは uv が仮想環境を作る時 python を選ぶのに参考にされます。

uv インストール直後では　~/AppSata/roaming/uv/.python-version は有りませんが、powershellで

uv python pin <pythonバージョン> --global

と打つと、~/AppSata/roaming/uv/.python-version ファイルが作成され　pythonバージョン　が格納されます。 さらに

uv python pin <pythonバージョン> --global

と打てば、~/AppData/roaming/uv/.python-version が更新されます。

残念ながら、この既定値をコマンドでクリアする方法は、現在のuvのバージョンでは無いようです。 この既定値をクリアするには ~/AppData/roaming/uv/.python-version を explorer や powershell などで削除してください。

幸いなことにこの既定値をクリアする必要性は滅多にありません。現在よく使う既定値は決まっているものだし、そうそう変わるものでもないからです。

注意！

uv python pin <pythonバージョン> --global

はシステムに 指定pythonバージョンのpythonランタイムが存在しないと、指定バージョンの managed pythonランタイムをインストールします。

uv init でプロジェクトに設定される pythonランタイムのバージョン

ここでは uv init で プロジェクトが初期化されるとき、プロジェクトにどの pythonランタイムバージョンが選ばれるかを説明します。

uv init で pythonバージョンを指定しない場合

~/AppSata/roaming/uv/.python-version ファイルが無いか、空の場合、uvで作るプロジェクトが仮想環境で使うpythonのバージョンは 以下のように決まります。

1. システムに system pythonしかなく、managed pythonが無い場合は、system pythonの最新版がプロジェクトが仮想環境で使うpythonのバージョンになります。
2. システムに managed python がある場合は、managed pythonの最新版がプロジェクトが仮想環境で使うpythonのバージョンになります。

例えば system python 3.13, 3.14 が有り、managed pythonが無い場合は、

uv init 

すると、プロジェクトが使う pythonバージョンは 3.14 になります。

system python 3.13, 3.14 が有り、managed pythonが 3.9, 3.10 が有る場合は プロジェクトが使う pythonバージョンは 3.10 になります。 つまり、managed pythonがある場合はそちらが優先で決まるということです。

プロジェクトが使用する pythonバージョンは tomlファイルとプロジェクトディレクトリに置かれた .python-versionファイルに設定されます。

~/AppSata/roaming/uv/.python-version ファイルで pythonバージョンが指定されている場合は プロジェクトの pythonバージョンは ~/AppSata/roaming/uv/.python-version になります・ プロジェクトの .python-versionファイルに ~/AppSata/roaming/uv/.python-version ファイルの内容がコピーされ tomlファイルにも設定されます。

uv init で pythonバージョンを指定する場合

uv init --python 3.13

のように、初期化時に pythonバージョンを指定すると、こちらが優先され、プロジェクトの pythonバージョンになります。

プロジェクトの .python-version と tomlファイルにpythonバージョンが設定されます。

いつ managed python がインストールされるのか

managed python は以下の契機でインストールされます。

1. uv python install <pythonバージョン> でインストールを指示し、指定バージョンの managed pythonが無かったとき
2. uv python pin <pythonバージョン> で プロジェクトの pythonバージョンを指示し、指定バージョンの pythonが無かったとき。
3. uv python pin <pythonバージョン> --global で プロジェクトの pythonバージョンを指示し、指定バージョンの pythonが無かったとき。
4. uv sync や uv venv で .python-version の指定する バージョンの pythonが無かった時
5. uv sync --python <pythonバージョン> や uv venv --python <pythonバージョン> で --python <pythonバージョン> で指定する バージョンの pythonが無かった時。但し、仮想環境が使う pythonバージョンは .python-version の指すものになります。この場合せっかく新たにインストールした managed pythonランタイムは使われないという奇妙なことになります。バグ？

注意 既定では managed python のコマンド名は python<バージョン名> ですが、 uv python install <pythonバージョン> --default で managed pythonをインストールすると python, python3 というコマンド名でもインストールされます。

python, python3 という名称は競合するため、最後にインストールした managed python を起動するものがインストールされます。

uv sync/venv が使う pythonはどれか

プロジェクトがある場合

uv sync が仮想環境作成に使う pythonバージョンは、プロジェクトの .python-version で指定されているものを使います。 つまり、uv init の段階で仮想環境にどの pythonを使うのかは決まっていると言えます。

uv sync/venv に --python <pythonバージョン> が指定されている場合は、そのバージョンが無ければ managed python をインストールしますが仮想環境が使うのはあくまで .python-version で指定されているpythonバージョンです。 ならば --python オプションなどサポートしなければ良いと思うのですが、現在はこういう仕様になっています。バグ？

uvは仮想環境を作成する時、

• 該当するバージョンの managed python が有ればそれを使います。
• 該当するバージョンの managed python が無い場合は、該当するバージョンの system python を使います。
• 両方なければ、managed pythonをインストールして使います。

uv venv の動きは、プロジェクトが存在している場合は基本的に uv sync と同じです。

プロジェクトが無い場合の uv venv

uv sync はプロジェクトが無いとエラーになりますが、uv venv はプロジェクトが無くても使うことができます。 この場合 uv venv は、プロジェクトの開発ではなく、仮想環境の構築のみの目的で使うことができます。

uv venv がプロジェクトの無い状態で叩かれた場合、仮想環境が使うpythonの選択は uv init と同じです。 つまり、

• ~/Appdata/Roaming/uv/.python-version が有ればそれに従います。
• ~/Appdata/Roaming/uv/.python-version もなく managed pythonランタイムがあればその最新版になります。
• ~/Appdata/Roaming/uv/.python-version もなく managed pythonランタイム もなければ system pythonランタイムの最新版になります。

uv venv --python <pythonバージョン> では 仮想環境が使う python のバージョンを自由に選ぶことができます。

• 該当するバージョンの managed python が有ればそれを使います。
• 該当するバージョンの managed python が無い場合は、該当するバージョンの system python を使います。
• 両方なければ、managed pythonをインストールして使います。

managed python は仮想環境専用？

managed python はグローバルな python として使用可能ですが、uv で仮想環境は作れますが、 仮想環境の外にパッケージをインストールすることはできません。 managed python は仮想環境専用の pythonと考えた方が良いでしょう。

グローバルなコマンドをパッケージとして managed pythonにインストールするには uv tool install を使うべきです。 これは仮想環境を自動的に作成し、パッケージをインストールして、パッケージがインストールした CLIコマンドを ~/.local/bin(パスの通ったディtレクトリ)にも置きます。pipx と同じ考え方で グローバルなpython環境を汚しません。