安装
方法一：使用安装脚本
# macOS 和 Linux
curl -LsSf https://astral.sh/uv/install.sh | sh# Windows PowerShell
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"方法二：使用包管理器
# macOS (Homebrew)
brew install uv# Windows (Scoop)
scoop install uv# 通过 pip 安装
pip install uv入门
使用虚拟环境
1. 创建虚拟环境
# 创建一个新的虚拟环境
uv venv myproject# 创建指定 Python 版本的虚拟环境
uv venv --python 3.11 myproject# 激活虚拟环境
# Linux/macOS:
source myproject/bin/activate
# Windows:
myproject\Scripts\activate2.安装包
# 安装单个包
uv pip install requests# 安装多个包
uv pip install requests numpy pandas# 安装指定版本的包
uv pip install "django>=4.0,<5.0"# 从 requirements.txt 安装
uv pip install -r requirements.txt使用uv方式
1.项目初始化
# 初始化一个新项目
uv init my_uv_test
cd my_uv_test# 查看项目结构
tree ..
├── main.py
├── pyproject.toml
└── README.md1 directory, 3 files使用 pyproject.toml 管理依赖
[project]
name = "my-uv-test"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.12"
dependencies = []3. 依赖管理
安装依赖
# 安装项目依赖（从 pyproject.toml）
uv pip install -e .# 安装开发依赖
uv pip install -e ".[dev]"# 安装所有可选依赖
uv pip install -e ".[dev,docs,web]"# 生成锁定文件
uv pip freeze > requirements.lock# 同步依赖（确保环境与 requirements.txt 完全一致）
uv pip sync requirements.txt添加依赖
# 添加生产依赖
uv add requests
uv add "django>=4.0,<5.0"
uv add requests beautifulsoup4 pandas# 添加开发依赖
uv add --dev pytest black flake8
uv add --dev "pytest>=7.0"# 添加可选依赖组
uv add --group docs sphinx sphinx-rtd-theme
uv add --group web fastapi uvicorn添加依赖后再次查看pyproject.toml
[project]
name = "my-uv-test"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.12"
dependencies = ["requests>=2.32.3",
]运行
uv run 选择 Python 版本的优先级顺序：
1. 明确指定版本（最高优先级）
uv run --python 3.11 script.py
uv run --python python3.12 script.py
uv run --python /usr/bin/python3.10 script.py2. 项目配置文件
如果有 pyproject.toml：
[project]
requires-python = ">=3.9"或者 .python-version 文件：
3.11.53. 环境变量
export UV_PYTHON=3.11
uv run script.py4. 系统默认 Python
如果以上都没有，uv 会按顺序查找：
python3python- 系统 PATH 中的第一个可用 Python
建议： 在项目中明确指定 Python 版本，避免环境差异导致的问题
使用 uv 一句话运行 Python 文件
uv run script.py在没有 pyproject.toml 的情况下，uv 有几种方式来处理依赖：
1. 使用 `--with` 参数临时安装包
uv run --with requests --with pandas script.py2. 通过脚本内联声明依赖（PEP 723）
在 Python 脚本顶部添加特殊注释：
# /// script
# dependencies = [
# "requests",
# "pandas>=1.0",
# ]
# ///import requests
import pandas as pd# 你的代码...然后直接运行：
uv run script.py3. 使用 requirements.txt
如果目录下有 requirements.txt，uv 会自动读取：
uv run script.py4. 完全不管理依赖
如果没有以上任何配置，uv run 会：
- 创建一个临时的虚拟环境
- 只安装 Python 标准库
如果脚本导入了第三方包但没有声明依赖，会报
ImportError
推荐做法： 使用 PEP 723 的内联依赖声明，这样脚本是自包含的，任何人都能直接用uv run script.py运行。
uv的优缺点
这是一份很好的 uv 使用指南！我来补充一下 uv 的优缺点分析：
uv 的优缺点
优点 ⭐
1. 极快的速度
- 用 Rust 编写，比 pip 快 10-100 倍
- 并行下载和安装包
- 智能缓存机制
2. 统一的工具链
# 一个工具搞定所有事情
uv venv # 创建虚拟环境
uv pip install # 包管理
uv run # 运行脚本
uv add # 添加依赖3. 现代化的依赖管理
支持
pyproject.toml- 自动生成锁定文件
- 依赖组管理（dev, docs, test 等）
4. 开箱即用
# 无需预先创建虚拟环境
uv run --with requests script.py5. PEP 723 支持
# /// script
# dependencies = ["requests"]
# ///
import requests6. 跨平台一致性
- Windows、macOS、Linux 行为一致
- 统一的安装方式
缺点 ⚠️
1. 生态系统兼容性
- 某些包的构建可能有问题
- 复杂的 C 扩展包支持不完善
- 企业环境的私有源配置较复杂
2. 学习成本
- 新的命令和概念
- 与传统 pip/virtualenv 工作流不同
- 团队需要统一工具
3. 相对年轻
- 社区相对较小
- 文档和教程不如 pip 丰富
- 可能存在未发现的 bug
4. 依赖 Rust 生态
- 某些平台可能缺少预编译二进制
- 从源码编译需要 Rust 工具链
适用场景
✅ 推荐使用
- 新项目开发
- 对速度有要求的 CI/CD
- 现代 Python 开发工作流
- 个人项目和学习
❌ 谨慎使用
- 传统企业环境
- 复杂的遗留项目
- 需要特殊包构建的项目
- 团队对新工具抗拒
总结
uv 是 Python 包管理的未来趋势，特别适合追求效率的现代开发者。虽然还有一些兼容性问题，但其速度和易用性优势明显，值得在新项目中尝试使用。
