uv

UV 是一个快速的 Python 包管理器和项目管理工具，用 Rust 编写，旨在替代 pip、pip-tools、pipx、poetry、pyenv、virtualenv 等工具。

安装 UV

Linux/macOS

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

Windows

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

通过 pip 安装

pip install uv

基本使用

1. 创建新的 Python 项目和环境

创建新项目

# 创建新项目目录和初始化
uv init my-project
cd my-project

# 或者在现有目录中初始化
uv init

指定 Python 版本创建项目

uv init --python 3.11 my-project

2. 管理 Python 环境

创建虚拟环境

# 创建虚拟环境（自动检测 Python 版本）
uv venv

# 指定 Python 版本创建虚拟环境
uv venv --python 3.11

# 指定虚拟环境名称
uv venv my-env

激活虚拟环境

# Linux/macOS
source .venv/bin/activate

# Windows
.venv\Scripts\activate

# 或者使用 uv 运行命令（推荐）
uv run python script.py

停用虚拟环境

deactivate

3. 包管理

安装包

# 安装单个包
uv add requests

# 安装多个包
uv add requests pandas numpy

# 安装开发依赖
uv add --dev pytest black

# 安装指定版本
uv add "requests>=2.28.0"
uv add "pandas==1.5.0"

# 从 requirements.txt 安装
uv add -r requirements.txt

移除包

# 移除单个包
uv remove requests

# 移除多个包
uv remove requests pandas

更新包

# 更新所有包
uv lock --upgrade

# 更新特定包
uv add requests --upgrade

4. 运行 Python 代码

使用 uv run 运行代码

# 运行 Python 脚本
uv run python script.py

# 运行模块
uv run python -m pytest

# 运行带参数的脚本
uv run python script.py --arg value

运行一次性脚本

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

5. 管理 requirements.txt

生成 requirements.txt

# UV 使用 pyproject.toml 管理依赖，但可以导出为 requirements.txt
uv pip freeze > requirements.txt

# 或者使用
uv export --format requirements-txt --output-file requirements.txt

从 requirements.txt 安装

# 方法 1：使用 uv add
uv add -r requirements.txt

# 方法 2：使用 uv pip（在虚拟环境中）
uv pip install -r requirements.txt

手动编辑 pyproject.toml

UV 主要使用 pyproject.toml 文件管理依赖：

[project]
name = "my-project"
version = "0.1.0"
dependencies = [
    "requests>=2.28.0",
    "pandas>=1.5.0",
    "numpy>=1.24.0",
]

[project.optional-dependencies]
dev = [
    "pytest>=7.0.0",
    "black>=22.0.0",
    "flake8>=5.0.0",
]

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

6. 锁定依赖

生成锁定文件

# 生成 uv.lock 文件（锁定确切版本）
uv lock

# 更新锁定文件
uv lock --upgrade

从锁定文件安装

# 安装锁定的依赖版本
uv sync

# 仅安装生产依赖
uv sync --no-dev

7. Python 版本管理

列出可用的 Python 版本

uv python list

安装特定 Python 版本

uv python install 3.11
uv python install 3.12

使用特定 Python 版本

uv run --python 3.11 python script.py

8. 常用工作流程

开始新项目

# 1. 创建项目
uv init my-project
cd my-project

# 2. 添加依赖
uv add requests pandas

# 3. 添加开发依赖
uv add --dev pytest black

# 4. 运行代码
uv run python main.py

克隆现有项目

# 1. 克隆项目
git clone <repository-url>
cd <project-directory>

# 2. 安装依赖
uv sync

# 3. 运行项目
uv run python main.py

9. 高级功能

使用工具

# 运行全局工具（类似 pipx）
uv tool run black .
uv tool run pytest

# 安装全局工具
uv tool install black
uv tool install pytest

缓存管理

# 查看缓存信息
uv cache info

# 清理缓存
uv cache clean

配置管理

# 查看配置
uv config list

# 设置配置
uv config set index-url https://pypi.org/simple/

10. 迁移指南

从 pip + requirements.txt 迁移

# 1. 在项目目录中初始化
uv init

# 2. 从 requirements.txt 添加依赖
uv add -r requirements.txt

# 3. 删除旧文件（可选）
rm requirements.txt

从 Poetry 迁移

# 1. 初始化 UV 项目
uv init

# 2. UV 可以直接读取 pyproject.toml
uv sync

11 设置超时时间

UV_HTTP_TIMEOUT=60 uv sync

常见问题

Q: 如何在 CI/CD 中使用 UV？

# GitHub Actions 示例
- name: Install uv
  uses: astral-sh/setup-uv@v1

- name: Install dependencies
  run: uv sync

- name: Run tests
  run: uv run pytest

Q: 如何处理私有包源？

# 设置私有源
uv config set index-url https://private-pypi.company.com/simple/

# 或在 pyproject.toml 中配置
[[tool.uv.index]]
name = "private"
url = "https://private-pypi.company.com/simple/"

Q: 如何查看已安装的包？

# 列出当前环境的包
uv pip list

# 查看包信息
uv pip show requests

Q: 如何换源？

# 使用阿里云镜像源
export UV_INDEX_URL=https://mirrors.aliyun.com/pypi/simple/
uv pip install [包名]

# 或清华大学镜像源
export UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple/

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

最佳实践

1. 使用 uv run 而不是激活环境：uv run 会自动处理环境激活

2. 提交 uv.lock 文件：确保团队使用相同的依赖版本

3. 使用 pyproject.toml：现代 Python 项目标准

4. 定期更新依赖：使用 uv lock --upgrade

5. 分离开发和生产依赖：使用 --dev 标志

参考链接

• UV 官方文档

• UV GitHub 仓库

• Python 打包用户指南