Python uv的使用和配置
一、uv 简介
uv 是由 Astral 团队（Ruff 工具的开发者）基于 Rust 编写的高性能 Python 包管理工具，旨在替代 pip、virtualenv 等传统工具。其核心优势包括：
- 极速性能：依赖解析和安装速度比
pip快 10-100 倍，尤其适合大型项目或 CI/CD 环境。 - 功能集成：
- 统一管理包安装、虚拟环境、Python 版本和依赖锁定。
- 支持
pyproject.toml和uv.lock文件，确保环境一致性。
- 兼容性：
- 兼容现有
requirements.txt和pip命令。 - 跨平台支持（Windows/macOS/Linux）。
- 兼容现有
二、常用 uv 命令速查
按功能分类整理如下：
| 功能类别 | 命令示例 | 作用 |
|---|---|---|
| 虚拟环境管理 | uv venv | 创建虚拟环境（默认生成 .venv 目录） |
uv venv --python 3.12 | 指定 Python 版本创建环境 | |
| 依赖管理 | uv add requests | 添加依赖并更新 pyproject.toml |
uv add --dev pytest | 添加开发依赖 | |
uv remove flask | 移除依赖 | |
uv sync | 根据 pyproject.toml 和 uv.lock 同步环境 | |
uv pip install -r requirements.txt | 从文件安装依赖（加速版 pip） | |
| 项目初始化 | uv init | 初始化项目（生成 pyproject.toml 和 uv.lock） |
| 工具执行 | uv run python app.py | 在虚拟环境中运行脚本（自动激活环境） |
uvx ruff check . | 直接运行工具（无需安装） | |
| Python 版本管理 | uv python install 3.12 | 安装指定 Python 版本 |
| 依赖分析 | uv tree | 查看依赖树 |
注：更多命令可通过
uv --help查看。
三、从零构建虚拟环境：完整流程
步骤 1：安装 uv
# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"# 或通过 pip（需环境隔离）
pipx install uv # 推荐
pip install uv # 备用
安装后验证：uv --version。
步骤 2：创建虚拟环境
uv venv .venv # 创建虚拟环境到 .venv 目录
uv venv --python 3.11 # 指定 Python 版本
步骤 3：激活虚拟环境
# macOS/Linux
source .venv/bin/activate# Windows
.venv\Scripts\activate
步骤 4：安装与管理依赖
uv add flask # 添加生产依赖（自动更新 pyproject.toml）
uv add --dev pytest # 添加开发依赖
uv sync # 同步所有依赖到环境
步骤 5：运行项目
uv run python app.py # 自动在虚拟环境中执行
步骤 6：依赖一致性保障
- 生成锁文件：
uv lock（根据pyproject.toml生成uv.lock）。 - 导出传统依赖文件：
uv export -o requirements.txt。
四、实战示例：Flask 项目初始化
$ mkdir myapp && cd myapp$ uv init # 生成 pyproject.toml README.md main.py
Initialized project `myapp`
$ ls
main.py pyproject.toml README.md
$ cat pyproject.toml
[project]
name = "myapp"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.11"
dependencies = []
$ uv add flask # 添加 Flask 依赖
Using CPython 3.11.11
Creating virtual environment at: .venv
Resolved 9 packages in 656ms
Prepared 6 packages in 661ms
Installed 7 packages in 3ms+ blinker==1.9.0+ click==8.2.1+ flask==3.1.1+ itsdangerous==2.2.0+ jinja2==3.1.6+ markupsafe==3.0.2+ werkzeug==3.1.3
$ uv sync # 安装依赖到虚拟环境
Resolved 9 packages in 0.54ms
Audited 7 packages in 0.00ms
$ ls
main.py pyproject.toml README.md uv.lock
$ cat pyproject.toml
[project]
name = "myapp"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.11"
dependencies = ["flask>=3.1.1",
]
$ gedit app.py
输入
from flask import Flask
app = Flask(__name__)@app.route("/")
def hello():return "Hello, UV!"if __name__ == "__main__":app.run(host="0.0.0.0", port=4500) # 显式启动服务器
运行：
$ uv run python app.pyuv run python app.py * Serving Flask app 'app'* Debug mode: off
WARNING: This is a development server. Do not use it in a production deployment. Use a production WSGI server instead.* Running on all addresses (0.0.0.0)* Running on http://127.0.0.1:4500* Running on http://192.168.0.3:4500
Press CTRL+C to quit
访问 http://localhost:4500 即可查看结果。
五、配置优化技巧
- 安装包配置源
$ uv pip install -r requirements.txt -i https://mirrors.aliyun.com/pypi/simple
or
uv add requests --default-index https://mirrors.aliyun.com/pypi/simple
- 切换国内镜像源（如阿里源）：
在 ~/.config/uv/uv.toml 中添加：
$ cat ~/.config/uv/uv.toml
[[index]]
url = "https://mirrors.aliyun.com/pypi/simple/"
default = true # 设为默认源
- 离线模式：
uv sync --offline仅使用本地缓存。
六、与传统工具对比
| 工具 | 优势场景 | 局限性 |
|---|---|---|
uv | 速度极快、依赖锁定、一体化管理 | 较新，生态兼容性在演进中 |
pip | 原生支持、无需额外安装 | 速度慢、无依赖锁定 |
conda | 数据科学库支持、跨语言依赖 | 体积大、启动慢 |
poetry | 依赖分组、打包发布 | 学习曲线陡峭 |
推荐新项目优先使用
uv，复杂科学计算场景考虑conda。
通过 uv，开发者可大幅提升环境构建效率，彻底解决“依赖漂移”问题，实现开发与生产环境 100% 一致。