Python UV 使用手册
Python UV 使用手册
网页收藏夹使用
一、常用命令
# 项目初始化 [默认当前文件夹]
uv init [project_name]
# 创建虚拟环境
uv venv
# 指定 Python 版本
uv venv --python 3.11
# 激活环境
.venv\Scripts\activate
# 运行脚本
uv run script.py
# 添加依赖（会更新 pyproject.toml）
uv add flask [--dev]
# 安装依赖（不更新配置文件）
uv pip install flask
# 同步项目依赖
uv sync
# 更新依赖
uv sync --upgrade
# 更新特定包
uv sync --upgrade-package flask
二、更换国内源（挑一个）
1 项目配置
pyproject.toml 添加
[[tool.uv.index]]
url = "https://pypi.tuna.tsinghua.edu.cn/simple"
default = true
uv.toml 添加
[[index]]
url = "https://pypi.tuna.tsinghua.edu.cn/simple"
default = true
2 环境变量
终端临时用
uv add --default-index https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple fastmcp
系统永久
vi ~/.bashrc
export UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple
# 额外镜像地址
export EXTRA_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple
三、安装 UV
1 macOS 和 Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
2 Windows
在 PowerShell 中执行以下命令：
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
验证安装
uv --version
四、依赖管理
1 安装依赖
uv add fastmcp
uv pip install fastmcp
开发环境用：--dev
指定生成环境：--production
uv add "numpy; python_version >= '3.11'; sys_platform == 'linux'"
2 删除依赖
uv remove fastmcp
uv pip uninstall fastmcp
3 查看依赖
uv pip list
4 导出依赖
uv pip freeze > requirements.txt
uv pip compile pyproject.toml -o requirements.txt
5 批量安装
uv pip install -r requirements.txt
uv add -r requirements.txt
uv pip install -r pyproject.toml
6 清除缓存
uv cache clean
uv pip cache purge
7 项目依赖树
uv tree
8 改习惯
将以前的 pip xxx 替换为 uv pip xxx
# 批量安装并生成锁定文件（类似 pip-tools）
uv pip compile ./requirements.in --universal --output-file ./requirements.txt
全局系统级别使用，添加 --system 参数:
uv pip install --system pandas
五、项目管理与锁定文件
1 初始化项目，管理依赖
uv init hello-world # 初始化项目
cd hello-world
uv add 'requests==2.31.0' # 增加依赖
uv lock --upgrade-package requests # 更新项目依赖
uv remove requests # 删除项目依赖
2 项目结构
.
├── .venv
│ ├── bin
│ ├── lib
│ └── pyvenv.cfg
├── .python-version
├── README.md
├── main.py
├── pyproject.toml
└── uv.lock
3 运行项目脚本
运行项目脚本
4 更新配置项目环境
git clone git/yb-mrp.git && cd yb-mrp
uv sync # 已存在项目安装项目依赖（自动解析锁定文件）
5 显示项目的依赖项树
uv tree --outdated # 以树形查看更新包
uv tree --depth 2 # 查看2级的依赖，防止依赖树过大
六、管理全局 CLI 工具：替代 pipx
# 全局安装 black 代码格式化工具（类似 pipx）
$ uv tool install black
$ uv tool run black ./myfile.py # 运行全局工具
# 同时提供更易用的 uvx 命令，类似 JavaScript 生态中的 npx
$ uvx pycowsay 'hello world!'
Installed 1 package in 19ms
------------
< hello world! >
------------
\ ^__^
\ (oo)\_______
(__)\ )\/\
||----w |
|| ||
$ uvx ruff format ./myscript.py
七、Python 版本管理：替代 pyenv
1 配置源
windows
env:UV_PYTHON_INSTALL_MIRROR="https://gh-proxy.com/github.com/indygreg/python-build-standalone/releases/download"
2 安装指定 python
uv python install 3.13.2
3 查看已安装和可安装的 Python 版本
uv python list
4 使用特定版本运行脚本
uvx python@3.13.2 -c "print('hello world')"
5 镜像
https://mirror.nju.edu.cn/github-release/indygreg/python-build-standalone/
八、虚拟环境管理: 虚拟环境管理
1 创建并激活
uv venv
source .venv/bin/activate
uv venv [venv_dir] [-p 3.14]
2 退出
deactivate
uv venv --seed # 强制安装基础包（如pip, setuptools, wheel）
九、工作区支持
工作区通过将大型代码库拆分为具有共同依赖项的多个包来组织大型代码库。在工作区中，每个包定义自己的pyproject.toml ，但工作区共享一个锁定文件，确保工作区以一组一致的依赖项运行。实现 Python 版本的 Monorepo 开发模式。
要创建工作区，请将tool.uv.workspace表添加到pyproject.toml ，这将隐式创建以该包为根的工作区。
[project]
name = "albatross"
version = "0.1.0"
requires-python = ">=3.12"
dependencies = ["bird-feeder", "tqdm>=4,<5"]
[tool.uv.sources]
bird-feeder = { workspace = true }
[tool.uv.workspace]
members = ["packages/*"]
exclude = ["packages/seeds"]
工作区目录:
albatross
├── packages
│ ├── bird-feeder
│ │ ├── pyproject.toml
│ │ └── src
│ │ └── bird_feeder
│ │ ├── __init__.py
│ │ └── foo.py
│ └── seeds
│ ├── pyproject.toml
│ └── src
│ └── seeds
│ ├── __init__.py
│ └── bar.py
├── pyproject.toml
├── README.md
├── uv.lock
└── src
└── albatross
└── main.py
它们会公用一个虚拟环境和锁文件。uv 会处理好不同包之间的依赖关系。
运行具体的包命令:
uv run --package bird-feeder
十、全局缓存与去重
uv 使用缓存来避免重新下载（和重新构建）在先前运行中已经访问过的依赖项。
1 看缓存路径
uv cache dir
# D:\Programs\uv\cache
2 删除所有缓存。
uv cache clean
3 删除未使用的缓存条目
uv cache purge
4 配置缓存路径和从全局缓存中使用包的方式：
$env:UV_CACHE_DIR=/path/to/code
$env:UV_LINK_MODE=hardlink
十一、迁移
pip 迁移到 uv
uv add -r requirements.txt
conda 迁移到 uv
导出依赖文件 requirements.txt
conda list -e > requirements.txt
使用想使用 uv pip 管理依赖
uv pip install -r requirements.txt
如果想使用 uv 项目作为管理
uv add -r requirements.txt
十一、PyTorch 场景适配
PyTorch 生态系统是深度学习研究和开发的热门选择。随着 anaconda 许可证变更，对商业许可证的判断更加严格，以及 PyTorch 官方后续不再维护 conda 渠道发行版本，您可以使用 uv 来管理不同 Python 版本和环境中的 PyTorch 项目和 PyTorch 依赖项，甚至可以控制镜像加速index-url的选择（例如，仅 CPU 与 CUDA）。
如下配置，可以看到基于不同的操作系统，我们可以安装不同的 torch 版本，windows 版本安装 cpu 版本的 torch，linux 版本安装 cuda 12.4 版本的 torch。
[project]
name = "project"
version = "0.1.0"
requires-python = ">=3.12.0"
dependencies = [
"torch>=2.6.0",
]
[tool.uv.sources]
torch = [
{ index = "pytorch-cpu", marker = "sys_platform != 'linux'" },
{ index = "pytorch-cu124", marker = "sys_platform == 'linux'" },
]
[[tool.uv.index]]
name = "pytorch-cpu"
url = "https://pypi.tuna.tsinghua.edu.cn/simple"
explicit = true
[[tool.uv.index]]
name = "pytorch-cu124"
url = "https://mirror.sjtu.edu.cn/pytorch-wheels/cu124"
explicit = true
十二、报错汇总
环境污染
报错： No solution found when resolving dependencies for split (python_full_version == '3.9.*'):
解决：
解决办法：退出其他 python 虚拟环境，只使用 uv 创建的虚拟环境，
检查 pyproject.toml 和 .python-version、uv.lock 中 requires-python 版本，
修改 pyproject.toml 中 python 版本和删除 uv.lock，执行 uv sync
虚拟环境未激活导致命令失败
使用uv run无需手动激活环境，直接执行命令；如果手动激活，需通过 uv sync 确保环境最新。
依赖升级后锁文件未更新
直接修改 pyproject.toml 中的版本约束后，必须运行 uv lock 重新生成锁文件，仅 uv sync 不会更新版本。
十三、更新环境依赖
- 直接将 pyproject.toml 这个文件中的某依赖删除
- 执行
uv lock：根据 pyproject.toml 更新 uv.lock 文件。 - 执行
uv sync：根据 uv.lock 的要求生成实际 python 环境。 - 执行
uv pip list： 查看当前依赖
ps: uv 管理项目的移植后，python 环境安装只需要执行 uv sync 即可将项目中记录的 python 环境建立起来
十四、构建与发布
1. 构建发行包
uv 支持生成标准的 Python 发行包（源包和 wheel 包），只需：
uv build # 在当前目录构建项目
ls dist/ # 查看生成的发行包（.tar.gz 和 .whl 文件）
或
uv build src/my_package # 构建指定目录的包
uv build --package my_lib # 构建工作区中的指定包
2. 发布
发布前需确保pyproject.toml包含正确的build-system定义。对于私有包，可添加分类器避免误上传：
配置 tom [可选]
[project]
classifiers = ["Private :: Do Not Upload"] # 标记为私有包（PyPI会拒绝）
发布时支持令牌认证（推荐使用，替代传统用户名密码）：
# 方式1：命令行直接指定令牌
uv publish --token YOUR_PYPI_TOKEN
# 方式2：通过环境变量安全传递（适合CI/CD）
export UV_PUBLISH_TOKEN=YOUR_PYPI_TOKEN
uv publish
3. 验证包安装（避免本地缓存干扰）
构建完成后，可通过隔离环境验证包是否可正常导入：
uv run --with my_package --no-project -- python -c "import my_package"
浙公网安备 33010602011771号