此文由 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 依賴，而 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 命令來兼容 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 這兩個包需要從該索引源安裝（注：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。