UV 学习记录

UV 是什么？#

UV 是一个用 Rust 编写的快速 Python 包/项目管理工具，旨在替代 pip、pip-tools、pipx、poetry、pyenv、virtualenv 等工具，提供统一而高效的体验。

安装#

Linux/macOS#

1
curl -LsSf https://astral.sh/uv/install.sh | sh

Windows（推荐）#

1
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

通过 pip 安装#

1
pip install uv

基本使用速查#

1) 创建项目与环境#

1
# 新建并初始化项目
2
uv init my-project
3
cd my-project
4

5
# 在现有目录初始化
6
uv init
7

8
# 指定 Python 版本
9
uv init --python 3.11 my-project

2) 管理 Python 环境#

1
# 创建虚拟环境（自动检测 Python）
2
uv venv
3

4
# 指定 Python 版本
5
uv venv --python 3.11
6

7
# 指定虚拟环境名称（如需）
8
uv venv my-env
9

10
# 激活（传统方式）
11
# Linux/macOS: source .venv/bin/activate
12
# Windows: .venv\Scripts\activate
13

14
# 推荐：无需显式激活，直接运行
15
uv run python script.py
16

17
# 停用（传统方式）
18
deactivate

3) 包管理#

1
# 安装包
2
uv add requests
3
uv add requests pandas numpy
4
uv add --dev pytest black
5
uv add "requests>=2.28.0"
6
uv add "pandas==1.5.0"
7

8
# 从 requirements.txt 安装
9
uv add -r requirements.txt
10

11
# 移除包
12
uv remove requests
13
uv remove requests pandas
14

15
# 更新
16
uv lock --upgrade      # 全部包
17
uv add requests --upgrade  # 指定包

4) 运行代码#

1
# 脚本/模块
2
uv run python script.py
3
uv run python -m pytest
4

5
# 带参数
6
uv run python script.py --arg value
7

8
# 一次性脚本（临时环境安装后运行）
9
uv run --with requests python -c "import requests; print(requests.get('https://httpbin.org/get').json())"

5) requirements.txt 管理#

1
# 由当前环境导出
2
uv pip freeze > requirements.txt
3

4
# 或直接导出
5
uv export --format requirements-txt --output-file requirements.txt
6

7
# 从 requirements.txt 安装
8
uv add -r requirements.txt
9
# 或（在虚拟环境中）
10
uv pip install -r requirements.txt

若需手动维护依赖，UV 主要使用 pyproject.toml：

1
[project]
2
name = "my-project"
3
version = "0.1.0"
4
dependencies = [
5
  "requests>=2.28.0",
6
  "pandas>=1.5.0",
7
  "numpy>=1.24.0",
8
]
9

10
[project.optional-dependencies]
11
dev = [
12
  "pytest>=7.0.0",
13
  "black>=22.0.0",
14
  "flake8>=5.0.0",
15
]
16

17
[build-system]
18
requires = ["hatchling"]
19
build-backend = "hatchling.build"

6) 锁定依赖#

1
# 生成/更新锁定文件 uv.lock
2
uv lock
3
uv lock --upgrade
4

5
# 按锁定版本安装
6
uv sync
7
uv sync --no-dev  # 仅生产依赖

7) Python 版本管理#

1
uv python list
2
uv python install 3.11
3
uv python install 3.12
4
uv run --python 3.11 python script.py

8) 常用工作流#

1
# 新项目
2
uv init my-project && cd my-project
3
uv add requests pandas
4
uv add --dev pytest black
5
uv run python main.py
6

7
# 克隆现有项目
8
git clone <repo> && cd <dir>
9
uv sync
10
uv run python main.py

9) 高级功能#

1
# 工具（类似 pipx）
2
uv tool run black .
3
uv tool run pytest
4
uv tool install black
5
uv tool install pytest
6

7
# 缓存
8
uv cache info
9
uv cache clean
10

11
# 配置
12
uv config list
13
uv config set index-url https://pypi.org/simple/

10) 迁移指南#

1
# 从 pip + requirements.txt 迁移
2
uv init
3
uv add -r requirements.txt
4
rm requirements.txt  # 可选
5

6
# 从 Poetry 迁移
7
uv init
8
uv sync

11) 设置超时时间#

1
UV_HTTP_TIMEOUT=60 uv sync

常见问题（FAQ）#

在 CI/CD 中使用 UV#

1
- name: Install uv
2
  uses: astral-sh/setup-uv@v1
3

4
- name: Install dependencies
5
  run: uv sync
6

7
- name: Run tests
8
  run: uv run pytest

配置私有源#

1
uv config set index-url https://private-pypi.company.com/simple/

或在 pyproject.toml：

1
[[tool.uv.index]]
2
name = "private"
3
url = "https://private-pypi.company.com/simple/"

查看已安装的包#

1
uv pip list
2
uv pip show requests

换源示例#

1
# 阿里云
2
export UV_INDEX_URL=https://mirrors.aliyun.com/pypi/simple/
3

4
# 清华
5
export UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple/
6

7
# 中科大
8
export UV_INDEX_URL=https://mirrors.ustc.edu.cn/pypi/simple/
9

10
# 使用示例
11
uv pip install <package-name>

最佳实践#

使用 uv run 代替手动激活环境
提交 uv.lock，确保团队一致性
以 pyproject.toml 为中心管理依赖
定期 uv lock --upgrade 更新依赖
使用 --dev 区分开发/生产依赖

参考#

UV 官方文档
UV GitHub 仓库
Python 打包用户指南