チューリングのE2E自動運転チームの岩政(@colum2131)です。

2024年8月20日にuvのマイナーバージョンが0.3.0にアップデートされました。元々、pipの代替として設計されていたuvが、Pythonのバージョン管理からパッケージ管理まで行えると発表されました。

以前の2024年7月にまとめた記事では、

将来的には、uvがRyeに代替されるよう

と書きましたが、実際、RyeやPoetryなどの代替としてuvのみでPythonのプロジェクト管理が可能になりました。Ryeで行っていた操作同様にuvで実行できるようになった印象もあります。

https://zenn.dev/turing_motors/articles/0f1a764d14f581

チューリングのメンバーでも熱心なuvファンがいるため、本記事では、uvの基本操作や、便利な機能をまとめます。

1. uvの基本操作

uvの公式ドキュメントはuvで整備されています。

1.1 uvのinstall

公式のuv - Getting startedに従ってインストールすることができます。mac OSまたはLinuxの場合は以下です。

curl -LsSf https://astral.sh/uv/install.sh | sh

インストール後にexec $SHELL -lなどでshellを再読み込みを行うとuvを起動できます。今回用いるuvのバージョンは以下です。

uv --version
> uv 0.3.1

また、PyPIからもuvのinstallが可能です。

pip install uv

pipx install uv

1.2 新規プロジェクトの初期化

Rye同様にinitで新規プロジェクトを作成することができます。my-projectは任意のプロジェクト名です。既に作成したいプロジェクト下にいる場合はuv initだけで作成できます。

uv init my-project
cd my-project

すると以下のディレクトリ構造が作成されて、pyproject.tomlも自動で生成されます。

.
├── README.md
├── pyproject.toml
└── src
    └── my_project
        └── __init__.py

pyproject.tomlの中身は以下のようになっています。

[project]
name = "my-project"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.12"
dependencies = []

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

1.3 パッケージの同期

pyproject.tomlをもとにパッケージをインストールします。以下のコマンドを実行できます。

uv sync

Rye同様に仮想環境として.venvが作成されて、また、uv.lockというlockファイルが生成されます。また、全てのパッケージを再インストールする場合はuv sync --reinstall で可能です。

1.4 仮想環境のアクティベート

以下のコマンドで仮想環境を有効化できます。

. .venv/bin/activate

無効化する場合は以下を実行します。

deactivate

1.5 Pythonバージョン変更

Rye同様にpinコマンドでPythonのバージョンを変更することが可能です。.python-versionファイルも生成されます。

uv python pin 3.10

また、プロジェクトを初期化する際にuv initの引数に--pythonまたは-pにバージョンを指定すれば良いです。

uv init my-project-3.10 -p 3.10

または、直接pyproject.tomlのrequires-python = ">=3.10,<3.11"のように書き換えてuv syncで更新することも可能です。

詳細な情報は公式のuv - Python versionsを参照してください。

1.6 パッケージの追加

uv addでパッケージを追加することが可能です。以下でnumpyをインストールします。

uv add numpy

バージョンを指定することも可能です。

uv add "numpy==1.26.4"

uv removeでパッケージを取り除くことも可能です。

uv remove numpy

既にrequirements.txtが存在する場合はuv add -rからインストールすることも可能です。

uv add -r requirements.txt 

また、 --devで開発用の依存パッケージとしてインストールすることも可能です。

uv add jupyterlab --dev

pyproject.tomlでは以下が追加されます。

[tool.uv]
dev-dependencies = [
    "jupyterlab>=4.1.6",
]

インストールしたパッケージはuv pip listで確認できます。

1.7 実行

仮想環境を有効化せずとも特定のスクリプトを実行する場合はuv runで実行可能です。例えば main.pyとして以下のスクリプトが存在するとき、

print("Hello!")

以下のコマンドで実行することができます。

uv run main.py

2. uvの便利な機能

2.1 uv venvによる仮想環境作成

uv initでなくても仮想環境だけを作成することができます。引数でターゲットパスを指定することができ、指定しない場合はカレントディレクトリに.venvを作成します。既に仮想環境が存在する場合は削除されて、新しい仮想環境を作成します。

uv venv my-project-venv

--pythonまたは-pでPythonのバージョンを指定することが可能です。

uv venv -p 3.10

パッケージを追加する場合は、uv pip installでインストールできます。

uv pip install numpy

インストールしたパッケージはuv pip listで確認できます。

これらの一連の操作は公式のuv - The pip interfaceを参照してください。

2.2 uvxを利用したツールの呼び出し

uvxはツールをインストールせずに呼び出すことが可能です。例えば、高速なPythonのリンターおよびコードフォーマッターであるruffを以下で呼び出すことが可能です。なお、下記のコマンドはuv tool run ruffと同様のものです。

uvx ruff

特定のバージョンで実行することができます。

uvx ruff@0.3.0 check

uvx ruff@latest check

特にruffなどの場合、そのプロジェクト下のpyproject.tomlの設定を用います。ruffやmypyなどの設定はこちらを参考にしてください。

https://zenn.dev/turing_motors/articles/0f1a764d14f581#4.2-ruffやmypyの設定

uvxの詳細は公式のuv - Using toolsを確認してください。

2.3 PyPIで利用できないパッケージをインストールする

公式のuv - Specifying dependenciesのDependency sourcesに記載される方法で、GitやURL、local wheelのパスなどをインストールすることが可能です。例えば、URLで特定のwheelを指定する場合だと以下のようにできます。

 uv add https://files.pythonhosted.org/packages/f7/29/13965af254e3373bceae8fb9a0e6ea0d0e571171b80d6646932131d6439b/setuptools-69.5.1-py3-none-any.whl

pyproject.tomlには新しく[tool.uv.sources]が追加されます。

dependencies = [
    "setuptools",
]

[tool.uv.sources]
setuptools = { url = "https://files.pythonhosted.org/packages/f7/29/13965af254e3373bceae8fb9a0e6ea0d0e571171b80d6646932131d6439b/setuptools-69.5.1-py3-none-any.whl" }

2.4 [tool.hatch.build.targets.wheel]によるモジュールアクセス

Rye同様に[tool.hatch.build.targets.wheel]をpyproject.tomlに記載して、ディレクトリ構造を気にすることなくモジュールをimportすることが可能になります。

[tool.hatch.build.targets.wheel]
packages = ["src/my_project", "src"]

2.5 CUDA依存のPyTorchをインストールするためのextra-index-urlの設定

Installing previous versions of PyTorchを参考のもと、CUDA versionにあっURLをpyproject.tomlのextra-index-urlを追加します。

[tool.uv]
extra-index-url = ["https://download.pytorch.org/whl/cu121"]

追加後に以下のコマンドでCUDA依存のPyTorchをインストールすることが可能です。

uv add "torch==2.4.0+cu121"

index-urlに指定することも可能ですが、デフォルトで "[https://pypi.org/simple](https://pypi.org/simple)"が指定されています。もし優先度を上げることが必要な状況なら以下のように記載すれば良さそう?です。詳細についてはuv - Settings#index-urlを参照してください。

[tool.uv]
index-url = "https://download.pytorch.org/whl/cu121"
extra-index-url = ["https://pypi.org/simple"]

find-linksも[tool.uv]で同様に設定可能です。

また、アーキテクチャごとにインストールするパッケージを変更する場合は、こちらの記事が強く参考になりました。

https://zenn.dev/mjun0812/articles/b22adf3fab1fdd

2.6 他ソフトウェアとの連携

公式のuv - Integration guidesにて、DockerやGihub Action、Pre-commitなどにおけるuvを統合する際のベストプラクティスが記載されています。

2.7 flash-attentionをインストールする

flash-attentionはtransformerモデルを高速に処理するための技術でflash-attnとしてパッケージ化されています。

こちらをuvでinstallする方法を以下でまとめました。

https://zenn.dev/colum2131/articles/342b7bdb20c54e

3. おわりに

いよいよuvだけでPythonのプロジェクト管理が完結しそうです。そもそもRyeと比較してuvの良かった機能として、cross-platform対応したwheelのURLがlockファイルに生成されていることがありました。今回のアップデートでRyeと同様の操作感で扱えるものになり、おそらくチューリングではPythonのプロジェクト管理はuvを中心に使っていくと思います。

今回のアップデートや公式ドキュメントが公開されたため、まだ知らない機能もあり、便利そうな機能は適宜追加していきます。また、紹介した機能で誤りもあるかもしれないため、コメントで教えていただけるとありがたいです。