はじめに

みんなが 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。