前言

皆さんは uv の速さ（UV：Python パッケージ管理の神器 - pip より 100 倍高速）を宣伝していますが、私たち研究室では複数のマシン間で Python 環境を移行する必要がある場合、uv による環境の再現性も注目すべき点です。

すでに同門に uv を推奨しようとしていますが、conda への依存が強く、新しいツールを試す意欲はあまりありません。そのため、uv の使い方について紹介するチュートリアルを書くことにしました。研究室の環境管理の変革を少しでも進めるためです。

uv のインストール

公式ドキュメント

Windows では winget を使うことをおすすめします：

Linux/macOS では、公式ドキュメントに従って curl/wget を使ってインストールできます：

uv 環境の初期化

新しいプロジェクトを初期化したい場合は、ワークスペースディレクトリで以下のコマンドを実行します：

あるいは既存の Python プロジェクトを uv 環境に移行したい場合は、プロジェクトディレクトリで以下のコマンドを実行します：

この時点でプロジェクトディレクトリに以下のファイルが作成されます：

1. .git、.gitignore、README.md については説明不要です。
2. main.py はサンプルの Python ファイルであり、不要であれば削除できます。
3. pyproject.toml は Python プロジェクトの設定ファイルで、プロジェクトのメタデータや依存関係などを記録しています。内容は大体以下の通りです： toml [project] name = "test-project" version = "0.1.0" description = "Add your description here" readme = "README.md" requires-python = ">=3.12" dependencies = []
4. .python-version は現在のプロジェクトの Python バージョンを指定するために使います。

Python バージョンの指定

pyproject.toml ファイル内の requires-python フィールドを編集し、現在のプロジェクトで必要な Python バージョンを指定します。例：==3.12、>=3.12 など。

その後、以下のコマンドを実行して指定されたバージョンの Python をインストールします：

仮想環境の作成

このコマンドは現在のプロジェクトディレクトリに仮想環境を作成し、.venv フォルダになります。その後、出力情報に従って仮想環境をアクティベートできます。例：

プロジェクトの依存関係の管理

基本的な使い方

新しい依存関係をインストールしたい場合は、以下のコマンドを使います：

これは以前の pip install を uv add に置き換えるだけですが、このコマンドは依存関係を仮想環境にインストールするだけでなく、pyproject.toml ファイルの dependencies フィールドに依存情報を自動的に書き込み、uv.lock ロックファイルを更新して依存関係のバージョンの再現性を確保します。uv.lock ファイルは手動で編集しないでくださいが、環境の再現には非常に重要です。.gitignore に入れないようにしてください。

たとえば requests をインストールした後、pyproject.toml には requests の依存関係が1つ追加されるだけで、uv.lock には requests およびそのすべてのサブ依存関係の詳細なバージョン情報が記録されます。uv tree コマンドで依存関係の木構造を確認できます：

不要な依存関係がある場合は、以下のコマンドでアンインストールできます：

インデックスソース

PyPI のミラーサイトを切り替えたい場合は、pyproject.toml ファイルに以下の内容を追加します（南大ミラーサイトを例にします）：

pip の index-url

一部のパッケージは独自の PyPI ミラーサイトに公開されています。たとえば torch の pip インストールコマンド（torch 公式ドキュメント 参照）は以下の通りです：

Using uv with PyTorch を参考に、pyproject.toml ファイルに以下の内容を追加する必要があります：

これを行わないと、CUDA 版の torch と torchvision がインストールされず、代わりに CPU 版がインストールされます。

まず、pytorch-cu130 という名前のインデックスソースを定義しています。url は上記の torch ドキュメントで示された --index-url と同じですが、ここでは南大ミラーサイト https://mirror.nju.edu.cn/pytorch/whl/cu130 に置き換えています。その後、tool.uv.sources で torch と torchvision という2つのパッケージがこのインデックスソースからインストールされることを指定しています（注：marker は、オペレーティングシステムが Linux または Windows の場合にのみ pytorch-cu130 インデックスを使用することを指定しています。macOS などの他のオペレーティングシステムでは、この設定は無視され、依然としてデフォルトのソースが使用されます）。

環境の再現

別のマシンで現在のプロジェクトの Python 環境を再現したい場合は、プロジェクトコードをクローンした後、以下のコマンドを実行します：

別のプロジェクトで同じ環境を再現したい場合は、pyproject.toml、uv.lock、.python-version ファイルをターゲットプロジェクトディレクトリにコピーし、pyproject.toml のプロジェクト情報を更新した後、同じコマンドを実行します：

パッケージのビルドと公開

あなたが他人がインストールできるような PyPI パッケージを書いている場合、開発時用の依存関係と実行時用の依存関係を区別する必要があります。開発用の依存関係は uv add --dev [package-name] コマンドを使ってインストールします。

その後、pyproject.toml ファイルにプロジェクト情報（作者、ライセンス、ビルド情報など）を補完する必要があります。研究活動では多くの場合パッケージを公開しないので、ここでは詳しく説明しませんが、以下の内容を参考にして理解してください：

その後、以下のコマンドでパッケージのビルドと公開が可能です：

その他の便利なコマンド

1. uv cache clear：uv のキャッシュをクリアし、使用しているディスク容量を解放します。
2. uv tree：現在のプロジェクトの依存関係の木構造を表示します。
3. uv run main.py：仮想環境をアクティベートした後に python main.py を実行するのと同等です。プロジェクト内の Python スクリプトを実行するのに使えます。
4. uvx [script-name]：ツールを実行します。一部の Python パッケージはコマンドラインツールを提供しており、uvx コマンドで実行できます。例：uvx NJUlogin -h。