uvでWindows11のPython環境を管理する

以前は、WindowsにPythonを公式インストーラーで直接インストールしていたけど、

次々と公開される研究の実装を動かして遊ぼうとすると、結局Pythonバージョンやパッケージバージョンの依存関係地獄にハマるので、プロジェクトごとに仮想環境を用意して切り分けることになる。

そんな流れで、動作が高速だと流行り(？)のuvという管理ツールを使ってみようかと↓

uv

Rustで書かれた非常に高速なPythonパッケージ・プロジェクトマネージャーです。



ウォームキャッシュを使用したTrioの依存関係インストール速度の比較

ハイライト

• 🚀 pip, pip-tools, pipx, poetry, pyenv, twine, virtualenvなどを1つのツールへ置き換えられる。
• ⚡️ pipよりも10～100倍高速。
• 🐍 複数のPythonバージョンのインストールと管理。
• 🛠️ Pythonアプリケーションの実行とインストール。
• ❇️ Script実行時のインラインでの依存関係メタデータをサポート。
• 🗂️ ユニバーサルロックファイルによる包括的なプロジェクト管理を提供。
• 🔩 pip互換のインターフェースを採用し、使い慣れたCLI操作そのままでパフォーマンスを向上。
• 🏢 スケーラブルなプロジェクト向けにCargoスタイルのワークスペースをサポート。
• 💾 依存関係の重複排除のためのグローバルキャッシュを備え、ディスク領域を効率的に使用する。
• ⏬ RustやPython無しでインストール可能だが、curlやpipによるインストールも可能。
• 🖥️ macOS, Linux, Windowsをサポート。

uvは、Ruffを開発したAstralによってサポートされています。

https://github.com/astral-sh/uv

ツール名が短か過ぎて検索しづらいし、3DCGの「UV座標」と混同しちゃうんだけど、短く(速く)シンプルにしようという意思は感じる。



uvはRustで書かれたツールで、Pythonに依存せず単独でインストールできる。PCにuvをインストールした上で、任意のバージョンのPythonをuv経由でインストールして管理できる。

Windows11にuvをインストール

PowerShellでの操作

Windows11の場合、PowerShellから以下のコマンドでインストールできる↓

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

※この操作はセキュリティソフトがブロックする可能性があるので、一時的に実行を許可するなどの対応が必要。

コマンドプロンプトでの操作

コマンドプロンプトで以下コマンドを打ってuvのバージョンが表示されたら、正常にインストールが完了している。

uv --version

ちなみに、インストール済みのuvを最新バージョンにアップデートするには以下のコマンド↓

uv self update

では、試しにGitHubからcloneした既存のPythonコードを実行する環境をuvで構築してみよう。個人的興味で、第1回Spatial AI勉強会で知ったDUSt3Rのリポジトリを使ってみる。

Windows11にDUSt3Rの実行環境を構築する

DUSt3RのREADMEのGet Startedをuvの操作に読み替えて進める。
結論から言うと、Windows11上での依存関係の解決に苦戦したので、その結果READMEで指定されているバージョンとは違う構成で構築しました。(DUSt3Rが依存しているCroCoのビルドでハマった)

Python以外のリソースのインストール

DUSt3RのREADMEではcondaで環境構築していてPython関係以外のインストールも含まれているので、まずはPython以外のリソースをWindows11にインストールする。
それぞれ公式ページからダウンロードしたインストーラーでインストール。

• CMake 3.31.4
• CUDA Toolkit 11.8
• cuDNN 8.7.0.84
• Microsoft Visual C++ 2019 (Visual Studio Community 2019)

DUSt3RのREADMEにはPython 3.11とCUDA 12.1が指定されてるけど、PyTorch公式のCUDA対応表と過去バージョンを見て、より安全な組み合わせを選択した。(PyTorchが依存しているtritonのWindows用ビルドは有志による配布で選択肢が少ないのもある)

uvからPythonのインストール

ここからはコマンドプロンプトでの操作。
uv経由でPythonをインストールする。(バージョンはDUSt3RのREADMEに従う)

以下コマンドでuv経由でPython 3.11をインストールする。

uv python install 3.11

このコマンドで、WindowsだとC:\Users\〇〇\AppData\Roaming\uv\python以下にPythonがインストールされる。

uvですでにインストール済みのPythonバージョン一覧を確認するには以下コマンド。

uv python list

DUSt3Rのリポジトリをクローン

(Gitはすでにインストールされている前提)

任意のディレクトリで以下コマンドを打ち、ローカルにDUSt3R一式をクローン。


git clone --recursive https://github.com/naver/dust3r


uvプロジェクトの作成

DUSt3R一式のディレクトリdust3rをuvのプロジェクトフォルダとしてプロジェクトを作成する。

uv init -app dust3r

-appはプロジェクトをアプリとして作成するためのオプション。今回はDUSt3RのGradio製のデモアプリ動かすので-appを選択。

このコマンドでdust3rディレクトリ直下にhello.pyが作成されるけど、今回は既存のPythonコードがあるので無視するか削除してしまって構わない。

仮想環境の作成

DUSt3Rのディレクトリへ移動。

cd dust3r

プロジェクトを作成すると自動的に仮想環境も作成されるけど、使用するPythonのバージョンを明示的に指定して仮想環境を作成するには以下コマンド↓

uv venv --python 3.11

作成済み仮想環境のPythonバージョンを変更するには以下コマンド↓

uv pin 3.11

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

作成した仮想環境をアクティベートするには以下コマンド↓

.venv\Scripts\activate

ちなみに、MacやLinux環境でアクティベートする場合は以下コマンド↓
source .venv/bin/activate

pyproject.tomlの編集

uvの大きな特長として、プロジェクトディレクトリ直下に.toml形式の設定ファイルpyproject.tomlがあり、この設定ファイルで仮想環境のPythonバージョンやパッケージバージョンの依存関係を管理できる。

仮想環境にパッケージを追加するには以下コマンド↓

uv add パッケージ名

仮想環境にパッケージがインストールされると、pyproject.tomlにもパッケージの情報が書き込まれる。

パッケージを削除するには以下コマンド↓

uv remove パッケージ名

requirements.txtを使ってパッケージを追加することもできる↓

uv add -r requirements.txt

DUSt3Rではrequirements_optional.txtもある↓

uv add -r requirements_optional.txt

pyproject.tomlを直接編集してその内容を仮想環境に反映することもできる。編集したpyproject.tomlの内容を反映するコマンドは以下↓

uv sync

例えば、PyTorchのGPU対応版はPyPIで配布されていないので、pyproject.tomlでダウンロードURLを指定する必要がある。
また、Windows環境の場合、PyTorchが依存しているtritonパッケージのWindows版は有志がビルドしたものを使用する。

DUSt3R用のpyproject.tomlは最終的に以下のようになった↓


ここまででDUSt3RのREADMEのInstallationの手順2までが完了。

RoPE用のcudaカーネルをコンパイルする

DUSt3RのREADMEのInstallationの手順3はオプション扱いだが、uvでの操作を書いておく。この手順によりcudaカーネルをコンパイルして実行時間を短縮できる。

crocoのディレクトリへ移動。

cd croco/models/curope/

uv runがPythonコマンドに相当する↓

uv run setup.py build_ext --inplace

元のディレクトリへ戻る。

cd ../../../

学習済みの重みをダウンロードする

dust3rディレクトリ直下にcheckpointsという名前のディレクトリを作成し、以下の学習済みの重みをダウンロードして配置する。

DUSt3Rのデモ(アプリ)を実行する

以下コマンドを実行すると、Gradio製のデモアプリが起動する。

uv run demo.py --model_name DUSt3R_ViTLarge_BaseDecoder_512_dpt

Webブラウザで127.0.0.1:7860にアクセスすれば、DUSt3Rのインタラクティブなデモを操作できる。

最終的にdust3rディレクトリは以下のようになった↓