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

2026年11月4日 (水) 13:19時点における版

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

はじめに

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

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

用語

pythonランタイム

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

system python

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

managed python

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

基本的なポリシー

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

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

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

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

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

uv は ~/AppSata/roaming/uv/.python-version に既定の pythonランタイムのバージョンを持ちます。 ファイル名は .python-version で中身は 3.14 とか 3.15 とか書かれます。

uv インストール直後ではこのファイルは有りませんが、powershellで

uv python pin <pythonバージョン> --global
例: uv python pin 3.13 --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バージョン>

はシステムに 指定pythonバージョンのpythonランタイムが存在しないと、指定バージョンの managed 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-versionファイルに ~/AppSata/roaming/uv/.python-version ファイルの内容がコピーされ tomlファイルにも設定されます。

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

uv init --python 3.13

のように、初期化時に 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が無かった時、指定バージョンの managed pythonがDLされます。。但しこれは少し複雑で、指定バージョンが toml の pythonバージョン条件を満足しない場合、.python-version の python が優先されます。この時エラーメッセージは出ますが、DLは実行されるので注意が必要です。

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

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

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

uv sync/venv が仮想環境作成に使う pythonバージョンは、原則 .python-version で指定されているものを使いますが、 uv sync/venv に --python <pythonバージョン> が指定されている場合は、そのバージョンを使います。 但し、--python <pythonバージョン> の指定が toml と反している場合は.python-version のものが使われます。

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