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

提供: tknotebook
移動: 案内、 検索
(→‎用語)
(→‎用語)
 
(1人の利用者による、間の28版が非表示)
6行: 6行:
 
uv はパッケージ管理ツールであると共に pythonランタイムを管理する管理ツールでもあります。
 
uv はパッケージ管理ツールであると共に pythonランタイムを管理する管理ツールでもあります。
 
この記事では uv がどのように pythonランタイムを管理するかを解説します。
 
この記事では uv がどのように pythonランタイムを管理するかを解説します。
 +
 +
uv の対象は Windows版 0.13.7 です。
 +
 +
尚この記事では Windows で uv を利用することを前提にします。
 +
linux や Mac では検証していませんのであしからず。
  
 
==用語==
 
==用語==
11行: 16行:
 
;pythonランタイム
 
;pythonランタイム
 
:特定のバージョンのpython一式のことです。pythonインタープリターや標準ライブラリやいくつかのツールの詰め合わせです。
 
:特定のバージョンのpython一式のことです。pythonインタープリターや標準ライブラリやいくつかのツールの詰め合わせです。
−
 
 
;system python
 
;system python
 
:uvが管理していない pythonランタイムです。
 
:uvが管理していない pythonランタイムです。
 
;managed python
 
;managed python
 
:uvが管理している pythonランタイムです。
 
:uvが管理している pythonランタイムです。
 +
;tomlファイル
 +
:正しい名称は pyproject.toml ファイル。プロジェクトの設定を保持するファイル
 +
;.python-version
 +
:プロジェクトが仮想環境で使用する pythonランタイムのバージョンを指定するファイル。pyproject.tomlに次いで重要な設定ファイル。
  
 
==基本的なポリシー==
 
==基本的なポリシー==
 +
 +
uv は uv が管理している Pythonランタイムを自由にインストールすることができます。
  
 
uv は自分が管理している managed python の利用に固執しません。適当な system python が存在していれば
 
uv は自分が管理している managed python の利用に固執しません。適当な system python が存在していれば
−
それを使うこともできます。その選択は uv の利用者に任されています。system python と managed python の共存も可能です。
+
それを使って仮想環境を作ることもできます。
 +
 
 +
system python と managed python の共存も可能ですが、
 +
uv は managed python があれば system python より優先して仮想環境に利用します。
  
 
==既定のpythonランタイムのバージョン==
 
==既定のpythonランタイムのバージョン==
  
−
uv は ~/appdata/
+
uvはプロジェクトを作成する際、既定の pythonバージョンを予め設定しておくことができます。
 +
uv python pin <pythonバージョン> --global
 +
例: uv python pin 3.13 --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バージョンを指定しない場合===
 +
 
 +
'''~/AppSata/roaming/uv/.python-version ファイルが無いか、空の場合'''、uvで作るプロジェクトが仮想環境で使うpythonのバージョンは
 +
以下のように決まります。
 +
 
 +
# システムに system pythonしかなく、managed pythonが無い場合は、system pythonの最新版がプロジェクトが仮想環境で使うpythonのバージョンになります。
 +
# システムに 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バージョンを指定すると、こちらが優先されます。
 +
 
 +
プロジェクトの .python-version と tomlファイルにpythonバージョンが設定されます。
 +
 
 +
==いつ managed python がインストールされるのか ==
 +
 
 +
managed python は以下の契機でインストールされます。
 +
 
 +
# '''uv python install <pythonバージョン>''' でインストールを指示し、指定バージョンの managed pythonが無かったとき
 +
# '''uv python pin <pythonバージョン>''' で プロジェクトの pythonバージョンを指示し、指定バージョンの pythonが無かったとき。
 +
# '''uv python pin <pythonバージョン> --global''' で プロジェクトの pythonバージョンを指示し、指定バージョンの pythonが無かったとき。
 +
# '''uv sync や uv venv''' で .python-version の指定する バージョンの pythonが無かった時
 +
# '''uv sync --python <pythonバージョン> や uv venv --python <pythonバージョン> ''' で --python <pythonバージョン> で指定する バージョンの pythonが無かった時。但しこれは少し複雑で、指定バージョンが 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をインストールして使います。

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

メインページ>コンピュータの部屋#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バージョンを予め設定しておくことができます。 

uv python pin <pythonバージョン> --global
例: uv python pin 3.13 --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バージョンを指定しない場合

~/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バージョンを指定すると、こちらが優先されます。

プロジェクトの .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が無かった時。但しこれは少し複雑で、指定バージョンが 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をインストールして使います。

「http://www.nakamuri.info/mw/index.php?title=Uv_が使うpythonランタイム&oldid=4841」から取得