「Uv が使うpythonランタイム」の版間の差分
(→既定のpythonランタイムのバージョン) |
(→用語) |
||
| (1人の利用者による、間の45版が非表示) | |||
| 16行: | 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に次いで重要な設定ファイル。 | ||
| + | ;パッケージのCLIコマンド | ||
| + | :python実行環境にパッケージをインストールすると、一緒にインストールされる CLI(コマンドラインインターフェース)コマンドです。詳細は'''「[[Pythonアプリケーションを起動する#パッケージのエントリポイントを実行する]]」''' 参照。 | ||
==基本的なポリシー== | ==基本的なポリシー== | ||
| 35行: | 40行: | ||
uvはプロジェクトを作成する際、既定の pythonバージョンを予め設定しておくことができます。 | uvはプロジェクトを作成する際、既定の pythonバージョンを予め設定しておくことができます。 | ||
| + | 現在よく使う pythonバージョンを設定しておくと便利です。 | ||
uv python pin <pythonバージョン> --global | uv python pin <pythonバージョン> --global | ||
例: uv python pin 3.13 --global | 例: uv python pin 3.13 --global | ||
| + | 既定値の設定では --global オプションを付けます。 | ||
| + | |||
uv は '''~/AppSata/roaming/uv/.python-version''' に'''既定の pythonランタイムのバージョン'''を格納します。 | uv は '''~/AppSata/roaming/uv/.python-version''' に'''既定の pythonランタイムのバージョン'''を格納します。 | ||
ファイルの中身は 3.14 とか 3.15 とかがテキストで書かれています。 | ファイルの中身は 3.14 とか 3.15 とかがテキストで書かれています。 | ||
| − | pythonランタイムバージョンは pythonが managed か system | + | pythonランタイムバージョンは '''pythonが managed か system かを指定しない'''ことに注意してください。 |
pythonランタイムバージョンは uv が仮想環境を作る時 python を選ぶのに参考にされます。 | pythonランタイムバージョンは uv が仮想環境を作る時 python を選ぶのに参考にされます。 | ||
| 53行: | 61行: | ||
この既定値をクリアするには ~/AppData/roaming/uv/.python-version を explorer や powershell などで削除してください。 | この既定値をクリアするには ~/AppData/roaming/uv/.python-version を explorer や powershell などで削除してください。 | ||
| − | + | 幸いなことにこの既定値をクリアする必要性は滅多にありません。現在よく使う既定値は決まっているものだし、そうそう変わるものでもないからです。 | |
'''注意！''' | '''注意！''' | ||
uv python pin <pythonバージョン> --global | uv python pin <pythonバージョン> --global | ||
| − | はシステムに | + | はシステムに 指定pythonバージョンのpythonランタイムが存在しないと、'''指定バージョンの managed pythonランタイムをインストールします'''。 |
| − | + | ||
==uv init でプロジェクトに設定される pythonランタイムのバージョン== | ==uv init でプロジェクトに設定される pythonランタイムのバージョン== | ||
| + | |||
| + | ここでは uv init で プロジェクトが初期化されるとき、プロジェクトにどの pythonランタイムバージョンが選ばれるかを説明します。 | ||
===uv init で pythonバージョンを指定しない場合=== | ===uv init で pythonバージョンを指定しない場合=== | ||
| − | '''~/AppSata/roaming/uv/.python-version ファイルが無いか、空の場合''' | + | ===='''~/AppSata/roaming/uv/.python-version ファイルが無いか、空の場合'''==== |
| + | uvで作るプロジェクトが仮想環境で使うpythonのバージョンは | ||
以下のように決まります。 | 以下のように決まります。 | ||
| 78行: | 88行: | ||
つまり、managed pythonがある場合はそちらが優先で決まるということです。 | つまり、managed pythonがある場合はそちらが優先で決まるということです。 | ||
| − | + | プロジェクトが使用する pythonバージョンは tomlファイルとプロジェクトディレクトリに置かれた '''.python-versionファイル'''に設定されます。 | |
| − | '''~/AppSata/roaming/uv/.python-version ファイルで pythonバージョンが指定されている場合''' | + | |
| − | プロジェクトの .python- | + | ===='''~/AppSata/roaming/uv/.python-version ファイルで pythonバージョンが指定されている場合'''==== |
| + | プロジェクトの pythonバージョンは '''既定のpythonバージョン(~/AppSata/roaming/uv/.python-version)''' になります・ | ||
| + | プロジェクトの '''.python-versionファイル'''に ~/AppSata/roaming/uv/.python-version ファイルの内容がコピーされ | ||
tomlファイルにも設定されます。 | tomlファイルにも設定されます。 | ||
===uv init で pythonバージョンを指定する場合=== | ===uv init で pythonバージョンを指定する場合=== | ||
uv init --python 3.13 | uv init --python 3.13 | ||
| − | のように、初期化時に | + | のように、初期化時に pythonバージョンを指定すると、こちらが優先され、プロジェクトの pythonバージョンになります。 |
プロジェクトの .python-version と tomlファイルにpythonバージョンが設定されます。 | プロジェクトの .python-version と tomlファイルにpythonバージョンが設定されます。 | ||
| 98行: | 110行: | ||
# '''uv python pin <pythonバージョン> --global''' で プロジェクトの pythonバージョンを指示し、指定バージョンの pythonが無かったとき。 | # '''uv python pin <pythonバージョン> --global''' で プロジェクトの pythonバージョンを指示し、指定バージョンの pythonが無かったとき。 | ||
# '''uv sync や uv venv''' で .python-version の指定する バージョンの pythonが無かった時 | # '''uv sync や uv venv''' で .python-version の指定する バージョンの pythonが無かった時 | ||
| − | # '''uv sync --python <pythonバージョン> や uv venv --python <pythonバージョン> ''' で --python <pythonバージョン> で指定する バージョンの | + | # '''uv sync --python <pythonバージョン> や uv venv --python <pythonバージョン> ''' で --python <pythonバージョン> で指定する バージョンの pythonが無かった時。但し後述しますが、ダウンロードされインストールされる Managed pythonランタイムがそのままプロジェクトの仮想環境に使われるわけではないので注意してください。 |
'''注意''' | '''注意''' | ||
| 105行: | 117行: | ||
python, python3 というコマンド名でもインストールされます。 | python, python3 というコマンド名でもインストールされます。 | ||
| − | python, python3 という名称は競合するため、最後にインストールした managed python | + | python, python3 という名称は競合するため、最後にインストールした managed python を起動するものがインストールされます。 |
==uv sync/venv が使う pythonはどれか== | ==uv sync/venv が使う pythonはどれか== | ||
| − | uv | + | ===プロジェクトがある場合=== |
| − | uv sync/venv に --python <pythonバージョン> | + | |
| − | + | 基本的に、プロジェクトの中では uv sunc/venv は .python-version で指定された pythonランタイムを使います。 | |
| + | |||
| + | つまり、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 と同じです。 | ||
| + | つまり、pythonバージョンは | ||
| + | * ~/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 のバージョンを自由に選ぶことができます。 | ||
| + | |||
| + | pythonのバージョンが決まると uv venv は以下のように仮想環境を作ります。 | ||
| + | |||
| + | * 該当するバージョンの managed python が有れば、仮想環境はそれを使います。 | ||
| + | * 該当するバージョンの managed python が無い場合は、仮想環境は該当するバージョンの system python を使います。 | ||
| + | * 両方なければ、仮想環境は managed pythonをインストールして使います。 | ||
| + | |||
| + | ==managed python は仮想環境専用？== | ||
| + | |||
| + | managed python はグローバルな python として使用可能ですが、uv で仮想環境は作れますが、 | ||
| + | '''managed python にパッケージをインストールすることはできません'''。 | ||
| + | managed python は仮想環境専用の pythonと考えた方が良いでしょう。 | ||
| − | + | グローバルなコマンドをパッケージとして managed pythonにインストールするには uv tool install を使うべきです。 | |
| − | + | これは仮想環境を自動的に作成し、パッケージをインストールして、パッケージがインストールした CLIコマンドを | |
| − | + | ~/.local/bin(パスの通ったディtレクトリ)にも置きます。pipx と同じ考え方で グローバルなpython環境を汚しません。 | |
2026年11月6日 (金) 08:48時点における最新版
メインページ>コンピュータの部屋#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に次いで重要な設定ファイル。
- パッケージのCLIコマンド
- python実行環境にパッケージをインストールすると、一緒にインストールされる CLI(コマンドラインインターフェース)コマンドです。詳細は「Pythonアプリケーションを起動する#パッケージのエントリポイントを実行する」 参照。
基本的なポリシー
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のバージョンは 以下のように決まります。
- システムに 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バージョンは 既定の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 は以下の契機でインストールされます。
- 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が無かった時。但し後述しますが、ダウンロードされインストールされる Managed pythonランタイムがそのままプロジェクトの仮想環境に使われるわけではないので注意してください。
注意 既定では managed python のコマンド名は python<バージョン名> ですが、 uv python install <pythonバージョン> --default で managed pythonをインストールすると python, python3 というコマンド名でもインストールされます。
python, python3 という名称は競合するため、最後にインストールした managed python を起動するものがインストールされます。
uv sync/venv が使う pythonはどれか
プロジェクトがある場合
基本的に、プロジェクトの中では uv sunc/venv は .python-version で指定された pythonランタイムを使います。
つまり、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 と同じです。 つまり、pythonバージョンは
- ~/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 のバージョンを自由に選ぶことができます。
pythonのバージョンが決まると uv venv は以下のように仮想環境を作ります。
- 該当するバージョンの managed python が有れば、仮想環境はそれを使います。
- 該当するバージョンの managed python が無い場合は、仮想環境は該当するバージョンの system python を使います。
- 両方なければ、仮想環境は managed pythonをインストールして使います。
managed python は仮想環境専用？
managed python はグローバルな python として使用可能ですが、uv で仮想環境は作れますが、 managed python にパッケージをインストールすることはできません。 managed python は仮想環境専用の pythonと考えた方が良いでしょう。
グローバルなコマンドをパッケージとして managed pythonにインストールするには uv tool install を使うべきです。 これは仮想環境を自動的に作成し、パッケージをインストールして、パッケージがインストールした CLIコマンドを ~/.local/bin(パスの通ったディtレクトリ)にも置きます。pipx と同じ考え方で グローバルなpython環境を汚しません。
