uvはPythonのバージョン管理とパッケージ管理のベストプラクティス
はじめに
Pythonの実行環境の構築方法は本当に様々で、ネット上にも情報が乱立している状況です。
私もこれまで「pyenv + pyenv-vertualenv」→「poetry」→「pyenv + venv」→「rye」と乗り換えてきました。ryeはPythonのバージョンの切り替えやパッケージ管理ができ、非常に高速に動作するのでしばらく使っていたのですが、2024年2月にryeのパッケージ管理の部分がAstralが開発をしているuvに置き換えられるようになり、さらに2024年8月にuv単体でもPythonのバージョン管理もできるようになってしまいました。
各種ツールの管理や、パッケージのビルド、CI/CDにも十分な機能が備わっているということで、これはもうuvだけでいいんじゃね？ということで、本記事ではuvについて紹介します。
※まだネット上ではuvに関する最新情報が少なく、uvとRyeを併用している例が見受けられますので、ご注意ください。
インストール方法
コマンドを１行入力するだけでインストールが完了します。
macOS or Linuxでは
curl -LsSf https://astral.sh/uv/install.sh | sh
Windowsでは
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
ターミナル等でuvと入力して、以下が表示されればインストール成功です。(１行目からuvのスピードが強調されていますね)
An extremely fast Python package manager.
Usage: uv [OPTIONS] <COMMAND>
...
他にもPyPI、Cargo、Homebrew、Wingetでもインストールできます。詳細はこちら。
プロジェクトの作成/プロジェクトへの導入
新しいPythonのプロジェクトを始めるのであれば、プロジェクトを作りたいディレクトリ内で
uv init [プロジェクト名]
です。README.md、hello.py、pyproject.toml、.python-versionという４つのファイルができます。
pyproject.tomlの中身は
[project]
name = "my-project"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.9"
dependencies = []
となっています。パッケージをインストールするとdependenciesにパッケージ名とバージョンが追加されていきます。
このファイルはsetup.pyに変わるもので、Python純正のメタデータを記載するためのファイルです。
poetryやryeでも使われています。
.python-versionには使用するPythonのバージョンが記載されています。
3.9
pyenvでpythonのバージョンを管理するときにも、同じファイルを使っていますので互換性があります。
次に使用するPythonを指定します。
uv python pin 3.12
例では3.12としましたがお好みのバージョンを指定してください。このときpyproject.tomlのrequires-pythonを満たしていないとエラーとなります。uv python pinは今自分が使うPythonのバージョンで、requires-pythonはこのプロジェクトを正常に動作させるためのPythonの条件をしていします。
ここまできたら、
uv sync
で指定したPythonがインストールされ、仮想環境がセットアップされます。このコマンドはpyproject.tomlに書かれているPythonとパッケージを依存関係も考慮してインストールしてくれます。GitHubなどからcloneしてきたプロジェクトにpyproject.tomlが入っていた場合にはこのuv syncでパッケージがインストールされます。
開発中のプロジェクトをuvに移行するには
何もパッケージ管理ツールを導入していないのであれば、プロジェクトのディレクトリでuv initすればOKです。もし必要なパッケージがrequirements.txtで管理していたのであれば、そのファイルをuv addでインストールするか、pyproject.tomlに追記してuv syncすればインストールされます。venvを使っていた場合は仮想環境はすでにできていますが、インストールされているパッケージがわからないので、pip freeze等で書き出して必要なパッケージのみをインストールします。
poetryやryeをすでに使っている場合には、すでにpyproject.tomlがあるので、uv syncのみで使い始められるます。
パッケージのインストール方法
パッケージのインストールは以下のコマンドでできます。
uv add [パッケージ名]
pip install [パッケージ名]に相当するものです。pipと比べるとコマンドも短く、インストールもメチャクチャ早いです。
パッケージの実態は.venv/lib/site-packagesにインストールされます。これはPython純正の仮想環境であるvenvと互換です。
逆にパッケージを削除する場合は
uv remove [パッケージ名]
です。インストールされたパッケージの情報はpyproject.tomlに追加されます。依存関係(インストールされたパッケージが必要とする他のパッケージ)もuv.lockに記録されます。(uv.lockが作られるおかげで、他の開発者がuv sync --frozenでuv.lockに書かれたパッケージを忠実にインストールして環境を完全に再現できます。)
次のようにpyproject.tomlを編集してdependenciesに必要なパッケージを手動で追加してuv syncすることでもインストールできます。
[project]
name = "my-project"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.9"
dependencies = [
"numpy==2.0.1",
"pandas>=2.2.2",
]
インストールされたパッケージとその依存関係はuv treeコマンドで見ることができます。
my-project v0.1.0
├── numpy v2.0.1
└── pandas v2.2.2
├── numpy v2.0.1
├── python-dateutil v2.9.0.post0
│ └── six v1.16.0
├── pytz v2024.1
└── tzdata v2024.1
ちなみに、ネット上の情報では多くがpipを使うことが前提となっていますが、uvではpipコマンドの代わりにuvコマンドを使う必要があります。混乱しないように、uvではuv pipというpip互換のコマンドを使うことができます。pip install [パッケージ名]はuv pip install [パッケージ名]、pip freezeはuv pip freezeで同様の動作をします。
コードの実行方法
uv run python [ファイル名]
で、構築した環境下でコードが実行できます。uv run --python 3.11 python [ファイル名]で、指定されたPythonのバージョン(この場合3.11)でコードを実行することもできます。
. .venv/bin/activateとすれば仮想環境に入ることもできるので、従来通りpython [ファイル名]でコードを実行できます。仮想環境から抜けるにはdeactivateとします。仮想環境に入るコマンドが用意されていないので、uv runで実行するのが正攻法かもしれないです。
Visual Studio Codeでコードを実行したりデバッグしたりする場合にはcommand + shift + P でコマンドパレットを出し、Python: Select Interpreterと入力します。実行環境の選択肢が一覧表示されるので、./.venv/bin/pythonがパスとして指定されているものを選んでおけばuvで構築した仮想環境のPythonが実行されます。
ツールのインストール方法
Python共通で使うツール(例えばコード整形・リンターツールのruffなど)をインストールする場合はuv tool install [ツール名]でインストールされ、仮想環境共通でツールが使えるようになります。
最後に
uvおすすめです！
初めての人でも簡単に導入できますし、他の環境構築ツールとの互換性が確保されているので、移行も安心です。Visual Studio Codeでもさっと使えます。全てのPythonプロジェクトをuvに移行しても問題ないぐらいです。
Discussion