uv 管理 Python 環境を使用する

この文は Mix Space によって xLog に同期更新されています
最適なブラウジング体験を得るために、元のリンクを訪れることをお勧めします
https://do1e.cn/posts/citelab/how-to-use-uv

前言#

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

すでに同門の皆さんに uv の使用を推奨していますが、皆さんは conda に対する依存が深く、新しいツールを試すことに消極的です。
したがって、uv の使用方法を紹介するチュートリアルを書くことに決めました。これにより、研究室の環境管理の変革を少し促進できればと思います。

uv のインストール#

公式ドキュメント

Windows では winget を使用してインストールすることをお勧めします：

winget install astral.uv

Linux/macOS では公式ドキュメントを参考にして curl/wget でインストールできます：

curl -LsSf https://astral.sh/uv/install.sh | sh
# または
wget -qO- https://astral.sh/uv/install.sh | sh

uv 環境の初期化#

新しいプロジェクトを初期化する必要がある場合は、あなたの workspace ディレクトリで次のコマンドを実行します：

uv init [project-name]
cd [project-name]

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

cd [project-name]
uv init

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

.git
.gitignore
main.py
pyproject.toml
.python-version
README.md

.git、.gitignore、README.md は説明の必要はありません
main.py はサンプルの Python ファイルで、必要なければ直接削除できます
pyproject.toml は Python プロジェクトの設定ファイルで、プロジェクトのメタデータや依存関係などの情報が記録されています。内容は大体以下のようになります：
```
[project]
name = "test-project"
version = "0.1.0"
description = "ここに説明を追加してください"
readme = "README.md"
requires-python = ">=3.12"
dependencies = []
```
.python-version は現在のプロジェクトの Python バージョンを指定するために使用されます

Python バージョンの指定#

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

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

uv python pin 3.12

仮想環境の作成#

uv venv

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

source .venv/bin/activate
# または Windows では
.venv\Scripts\activate

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

基本的な使い方#

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

uv add [package-name]

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

例えば requests をインストールした後、pyproject.toml には requests 依存関係が 1 つ追加され、uv.lock には requests およびそのすべてのサブ依存関係の具体的なバージョン情報が詳細に記録されます。依存関係ツリーを確認するには uv tree コマンドを使用します：

> uv tree
Resolved 6 packages in 0.75ms
test-project v0.1.0
└── requests v2.32.5
    ├── certifi v2025.11.12
    ├── charset-normalizer v3.4.4
    ├── idna v3.11
    └── urllib3 v2.6.1

もし不要な依存関係があれば、以下のコマンドでアンインストールできます：

uv remove [package-name]

可能な限り厳密に uv コマンドを使用して環境を管理してください。uv pip コマンドも提供されていますが、このコマンドは pyproject.toml と uv.lock ファイルを更新しないため、環境の再現性に問題を引き起こす可能性があります。

ミラーソース#

Pypi ミラーソースを変更する必要がある場合は、pyproject.toml ファイルに以下の内容を追加します（南大ミラーソースの例）：

[[tool.uv.index]]
name = "nju-mirror"
url = "https://mirror.nju.edu.cn/pypi/web/simple"
default = true

pip の index-url#

一部のパッケージは独自の PyPI ミラーソースで公開されます。例えば、torch の pip インストールコマンド（torch 公式ドキュメントを参照）：

pip3 install torch torchvision --index-url https://download.pytorch.org/whl/cu130

Using uv with PyTorch を参考にして、以下の内容を pyproject.toml ファイルに追加します：

[[tool.uv.index]]
name = "pytorch-cu130"
url = "https://download.pytorch.org/whl/cu130"
explicit = true

[tool.uv.sources]
torch = [
  { index = "pytorch-cu130", marker = "sys_platform == 'linux' or sys_platform == 'win32'" },
]
torchvision = [
  { index = "pytorch-cu130", marker = "sys_platform == 'linux' or sys_platform == 'win32'" },
]

そうしないと、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 環境を再現する必要がある場合は、プロジェクトコードをクローンした後、以下のコマンドを実行します：

uv sync

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

uv sync

パッケージの構築と公開#

他の人がインストールできる Pypi パッケージを書く場合、開発時依存関係と実行時依存関係を考慮する必要があります。開発依存関係は uv add --dev [package-name] コマンドでインストールする必要があります。

その後、pyproject.toml ファイルにプロジェクト情報（著者、ライセンス、構築情報など）を追加する必要があります。研究を行う際にはパッケージを公開しないことが多いため、ここでは詳しく説明しませんが、以下の内容を参考に理解してください：

[project]
name = "NJUlogin"
version = "3.6.1"
description = "南京大学のログインモジュールで、さまざまなキャンパスのウェブサイトにログインするために使用できます"
authors = [{ name = "Do1e", email = "[email protected]" }]
readme = "README.md"
requires-python = ">=3.10,<4.0"
dependencies = [
    "requests>=2.32.0",
    "pillow>=11.0.0",
    "numpy>=2.0.0",
    "lxml>=5.3.0",
    "pycryptodome>=3.21.0",
    "onnxruntime>=1.20.0",
    "cryptography>=43.0.0",
]
classifiers = [
    "Programming Language :: Python :: 3",
    "License :: OSI Approved :: MIT License",
    "Operating System :: OS Independent",
]


[project.scripts]
NJUlogin = "NJUlogin.__main__:main"

[tool.setuptools.packages.find]
include = ["NJUlogin", "NJUlogin.*"]

[project.urls]
Homepage = "https://github.com/Do1e/NJUlogin"
Repository = "https://github.com/Do1e/NJUlogin"

[dependency-groups]
dev = [
    "pre-commit>=4.3.0",
    "ruff>=0.14.6",
]

[[tool.uv.index]]
url = "https://mirror.nju.edu.cn/pypi/web/simple"
publish-url = "https://upload.pypi.org/legacy/"
default = true

[tool.ruff]
line-length = 100

[tool.ruff.lint]
ignore = ["C901", "E501", "E721", "E741", "F402", "F823"]
select = ["C", "E", "F", "I", "W"]

[tool.ruff.lint.isort]
lines-after-imports = 2

[tool.ruff.format]
quote-style = "double"
indent-style = "space"
skip-magic-trailing-comma = false
line-ending = "auto"

[build-system]
requires = ["setuptools>=61.0", "wheel"]
build-backend = "setuptools.build_meta"

[tool.uv]
package = true

その後、以下のコマンドを使用してパッケージを構築し、公開します：

uv build
uv publish

その他の便利なコマンド#

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