现代 Python 开发：uv 安装、配置与最佳实践
目录
- 一、uv 是什么？
- 二、uv 的安装
- 1. 通用安装方式（推荐）
- 2. 包管理器安装（可选）
- 3. 验证安装
- 三、uv 核心使用场景
- 1. 基础包安装/卸载
- 2. 虚拟环境管理
- 3. 项目依赖管理（兼容 pyproject.toml）
- 4. 运行 Python 代码/脚本
- 四、进阶用法
- 总结
一、uv 是什么？
uv是由 Astral 公司开发的 Rust 编写的 Python 工具链，核心优势是极速（比 pip 快 10-100 倍）、功能全面，集成了包安装、虚拟环境管理、依赖解析、项目构建等能力，兼容 pip/pipenv/poetry 的生态。
uv 官方文档（最核心）
地址：https://docs.astral.sh/uv/
这是uv最权威的使用指南，包含安装、基础用法、进阶功能、API 参考等所有内容，也是排查问题的首选。uv GitHub 源码仓库
地址：https://github.com/astral-sh/uv
可以查看源码、提交 Issue（反馈问题）、提 PR（贡献代码），也能在 Releases 页面下载指定版本的uv安装包，查看更新日志。uv 快速入门教程
地址： https://docs.astral.sh/uv/getting-started/
官方专为新手设计的快速上手指南，比完整文档更精简，适合刚接触uv时快速掌握核心用法。
二、uv 的安装
1. 通用安装方式（推荐）
适用于 macOS、Linux、Windows（PowerShell），执行以下命令自动下载适配系统的版本：
# macOS/Linuxcurl-LsSfhttps://astral.sh/uv/install.sh|sh# Windows (PowerShell)powershell-c"irm https://astral.sh/uv/install.ps1 | iex"2. 包管理器安装（可选）
- Homebrew (macOS/Linux)：
brewinstalluv - Cargo (Rust 环境)：
cargoinstalluv--locked - pip 安装（不推荐，仅应急）：
pipinstalluv
3. 验证安装
安装完成后，重启终端，执行以下命令验证：
uv--version# 输出示例：uv 0.1.37 (a1b2c3d 2026-03-03)三、uv 核心使用场景
1. 基础包安装/卸载
uv兼容 pip 的大部分用法，且默认使用虚拟环境（无需手动激活），核心命令如下：
| 功能 | uv 命令 | 说明 |
|---|---|---|
| 安装包 | uv pip install requests | 极速安装单个包 |
| 安装指定版本 | uv pip install requests==2.31.0 | 安装特定版本 |
| 从 requirements.txt | uv pip install -r requirements.txt | 批量安装依赖，速度远快于 pip |
| 升级包 | uv pip install --upgrade requests | 升级包到最新版本 |
| 卸载包 | uv pip uninstall requests | 卸载包 |
| 查看已安装包 | uv pip list | 列出当前环境的包 |
| 导出依赖 | uv pip freeze > requirements.txt | 导出已安装包到文件 |
2. 虚拟环境管理
uv内置虚拟环境功能，比venv更简洁：
# 创建虚拟环境（默认在 .venv 目录）uv venv# 激活虚拟环境# macOS/Linuxsource.venv/bin/activate# Windows (Cmd).venv\Scripts\activate.bat# Windows (PowerShell).venv\Scripts\Activate.ps1# 删除虚拟环境rm-rf.venv# macOS/Linuxrmdir/s .venv# Windows3. 项目依赖管理（兼容 pyproject.toml）
uv支持现代 Python 项目的pyproject.toml配置，替代requirements.txt：
# 初始化项目（生成 pyproject.toml）uv init my_projectcdmy_project# 添加依赖（自动写入 pyproject.toml）uvaddrequests# 生产依赖uvadd--devpytest# 开发依赖# 安装项目所有依赖（从 pyproject.toml）uvinstall# 同步依赖（移除未在 pyproject.toml 中声明的包）uvsync4. 运行 Python 代码/脚本
uv可直接运行代码，自动使用当前虚拟环境：
# 运行脚本uv run script.py# 运行临时代码uv run-c"print('Hello, uv!')"# 运行模块uv run-mhttp.server8000四、进阶用法
- 加速 pip 兼容：如果项目暂时不想切换到 uv 命令，可通过 uv 加速 pip：
uv pipinstallrequests# 等同于 pip install，但更快 - 指定 Python 版本：
uv可自动下载指定版本的 Python（需提前安装pyenv或uv内置的 Python 解析器）：uv pythoninstall3.11# 安装 Python 3.11uv run--python3.11script.py# 使用 3.11 运行脚本 - 缓存管理：
uv有全局缓存，清理缓存命令：uv cache clean# 清理所有缓存
总结
uv是高性能的 Python 包/环境管理工具，安装简单，兼容 pip/venv 生态，核心优势是速度快、功能集成度高。- 核心用法：
uv pip install（安装包）、uv venv（虚拟环境）、uv add（管理项目依赖）、uv run（运行代码）。 - 推荐在新项目中使用
uv init+pyproject.toml替代传统的requirements.txt，提升依赖管理规范性。