Uv が使うpythonランタイム

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

はじめに

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

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

用語

pythonランタイム

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

system python

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

managed python

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

基本的なポリシー

uv は自分が管理している managed python の利用に固執しません。適当な system python が存在していれば それを使うこともできます。その選択は uv の利用者に任されています。system python と managed python の共存も可能です。

既定の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バージョン> で プロジェクトの pythonバージョンを指示し、指定バージョンの pythonが無かったとき。
4. uv sync や uv venv で .python-version の指定する バージョンの pythonが無かった時
5. uv sync --python <pythonバージョン> や uv venv --python <pythonバージョン> で --python <pythonバージョン> で指定する バージョンの pythonが無かった時。但しこれは少し複雑で、指定バージョンが toml の pythonバージョン条件を満足しない場合、.python-version の python が優先されます。