uv で Python の環境構築
nukopyインストール
curl -LsSf https://astral.sh/uv/install.sh | sh
brew install あったのでやっぱり Homebrew でインストールすることにした。
ひとまずアンインストール。
rm ~/.cargo/bin/uv ~/.cargo/bin/uvx
brew install
brew install uv
バージョン
which uv
# /opt/homebrew/bin/uv
uv --version
# uv 0.4.16 (Homebrew 2024-09-24)
zsh の補完の設定
echo 'eval "$(uv generate-shell-completion zsh)"' >> ~/.zshrc
echo 'eval "$(uvx --generate-shell-completion zsh)"' >> ~/.zshrc
シェルを再起動して uv <Tab> を押すと以下のようにコマンドの候補が表示される（切れてるけどまあヨシ）
$ uv
add -- Add depend
build -- Build Pyth
build-backend -- The implem
cache -- Manage uv'
clean -- Clear the
export -- Export the
generate-shell-completion -- Generate s
help -- Display do
init -- Create a n
lock -- Update the
pip -- Manage Pyt
publish -- Upload dis
python -- Manage Pyt
remove -- Remove dep
run -- Run a comm
sync -- Update the
tool -- Run and in
tree -- Display th
venv -- Create a v
version -- Display uv
インストール可能な Python 処理系のリストを表示する
pyenv と違って CPython 以外の処理系の選択肢は現時点では pypy だけ。
このコマンドでは、システムや uv 以外でユーザがインストールした Python も表示してくれる。
uv python list
cpython-3.13.0rc2-macos-aarch64-none <download available>
cpython-3.12.6-macos-aarch64-none <download available>
cpython-3.12.3-macos-aarch64-none /usr/local/bin/python3.12 -> ../../../Library/Frameworks/Python.framework/Versions/3.12/bin/python3.12
cpython-3.12.3-macos-aarch64-none /usr/local/bin/python3 -> ../../../Library/Frameworks/Python.framework/Versions/3.12/bin/python3
cpython-3.12.3-macos-aarch64-none /opt/homebrew/opt/python@3.12/bin/python3.12 -> ../Frameworks/Python.framework/Versions/3.12/bin/python3.12
cpython-3.11.10-macos-aarch64-none <download available>
cpython-3.11.9-macos-aarch64-none /opt/homebrew/opt/python@3.11/bin/python3.11 -> ../Frameworks/Python.framework/Versions/3.11/bin/python3.11
cpython-3.10.15-macos-aarch64-none <download available>
cpython-3.9.20-macos-aarch64-none <download available>
cpython-3.9.6-macos-aarch64-none /Applications/Xcode.app/Contents/Developer/usr/bin/python3 -> ../../Library/Frameworks/Python3.framework/Versions/3.9/bin/python3
cpython-3.8.20-macos-aarch64-none <download available>
pypy-3.10.14-macos-aarch64-none <download available>
pypy-3.9.19-macos-aarch64-none <download available>
pypy-3.8.16-macos-aarch64-none <download available>
特定のバージョンの Python のインストール
インストール
uv python install cpython-3.12.6-macos-aarch64-none
確認する。ちゃんとインストールされてる。
uv python list
...
cpython-3.12.6-macos-aarch64-none /Users/nukopy/.local/share/uv/python/cpython-3.12.6-macos-aarch64-none/bin/python3 -> python3.12
...
uv でインストールした Python のみ表示する
uv python find
/Users/nukopy/.local/share/uv/python/cpython-3.12.6-macos-aarch64-none/bin/python3
プロジェクトの初期化
uv init コマンドで、pyproject.toml、.python-version、hello.py を作成できる（README.md とかも作成されるけど割愛）。
uv init
tree -a -L 1
.
├── .python-version
├── hello.py
└── pyproject.toml
システム内に Python 3.12.x 系がいくつかインストールされていたので、これらがちゃんと使い分けできるか試してみる。今システム内にインストールされているのは Python 3.12.3、3.12.6（先ほど uv でインストールしたバージョン）。
uv python list | grep 3.12
cpython-3.12.6-macos-aarch64-none /Users/nukopy/.local/share/uv/python/cpython-3.12.6-macos-aarch64-none/bin/python3 -> python3.12
cpython-3.12.3-macos-aarch64-none /usr/local/bin/python3.12 -> ../../../Library/Frameworks/Python.framework/Versions/3.12/bin/python3.12
cpython-3.12.3-macos-aarch64-none /usr/local/bin/python3 -> ../../../Library/Frameworks/Python.framework/Versions/3.12/bin/python3
cpython-3.12.3-macos-aarch64-none /opt/homebrew/opt/python@3.12/bin/python3.12 -> ../Frameworks/Python.framework/Versions/3.12/bin/python3
スクリプトの実行と処理系のバージョン切り替えをやってみる。
スクリプトの実行 & 処理系のバージョン切り替え
uv では、プロジェクト内のスクリプトを uv run xxx.py コマンドで実行できる。
今回実行するのは以下のスクリプト hello.py。現在の Python 処理系のバージョンを出力する単純なコード。
import sys
def main():
print(sys.version)
if __name__ == "__main__":
main()
pyproject.toml は初期化時のまま。
[project]
name = "uv-example"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.12"
dependencies = []
まずはデフォルトの .python-version を消して、uv run してみる。
rm .python-version
uv run hello.py
# Using CPython 3.12.6
# Creating virtual environment at: .venv
# ----- hello.py の出力 -----
# 3.12.6 (main, Sep 9 2024, 21:36:32) [Clang 18.1.8 ]
まず、.venv が作られ、その後、hello.py の出力で 3.12.6 が出力された。
3.12.6 が選択されたのは uv でインストールした Python が優先されるから？PATH の解決の順かと思って確認してみたけどそれは違った。そもそも ~/.local/share/uv/python/... には PATH が通ってなかったから関係なし。
uv run の挙動は「.venv を作成 & activate してその仮想環境内でスクリプトを実行」という形になっている。ちなむと、現段階では uv でインストールした Python はグローバルでは使えないらしい。将来的に機能追加する計画はあるみたい。
When Python is installed by uv, it will not be available globally (i.e. via the python command). Support for this feature is planned for a future release. In the meantime, use uv run or create and activate a virtual environment to use python directly.
次に .python-version で 3.12.3 にバージョンを固定して先程のスクリプトを実行する。
uv で作成したプロジェクトにおいて、Python バージョンは uv python pin <version> コマンドで固定できる。このコマンドを実行した時、プロジェクトルートに .python-version がない場合、自動で .python-version が作成される。
uv python pin 3.12.3
# Pinned `.python-version` to `3.12.3`
cat .python-version
# 3.12.3
uv run hello.py
# Using CPython 3.12.3 interpreter at: /usr/local/bin/python3
# Removed virtual environment at: .venv
# Creating virtual environment at: .venv
# ----- hello.py の出力 -----
# 3.12.3 (v3.12.3:f6650f9ad7, Apr 9 2024, 08:18:47) [Clang 13.0.0 (clang-1300.0.29.30)]
上記出力から以下の挙動を示すことが分かる。
-
uv python pinコマンドで処理系を切り替えることができる（というよりはuv run時に参照する.python-versionを書き換える） .python-versionで異なるバージョンに変更すると、次回のuv run実行時に仮想環境が作り直される
ひとまず特定のプロジェクトで Python を切り替える方法は理解できた。
nukopy
補足：pin コマンドの実装
実装見る限り pin コマンドは「システム内の使用可能な Python を探して .python-version を書き換える」ってことをしてるだけみたい。