用 uv 管理 Python 项目
uv 把虚拟环境、依赖管理、锁文件和 Python 版本管理整合到一个工具中,本文记录日常开发中最常用的工作流。
uv 是用 Rust 编写的 Python 包与项目管理工具。它可以替代 pip、venv、pip-tools 和 pyenv 的大部分功能,而且速度非常快。
初始化项目 #
uv init --package my-app
cd my-app
--package 会生成 src 布局的项目结构,适合需要打包或包含多个模块的项目:
my-app/
├── .python-version
├── README.md
├── pyproject.toml
└── src/
└── my_app/
└── __init__.py
.python-version 记录项目使用的 Python 版本。如果本机没有这个版本,uv 会自动下载。
管理依赖 #
uv add fastapi uvicorn # 添加运行时依赖
uv add --dev pytest # 添加开发依赖
uv remove uvicorn # 移除依赖
依赖会写入 pyproject.toml,同时更新 uv.lock:
[project]
dependencies = [
"fastapi>=0.115.0",
]
[dependency-groups]
dev = [
"pytest>=8.3.0",
]
重要
不要手动编辑 uv.lock,也不要在项目中混用 pip install。所有依赖变更都应通过 uv add / uv remove 完成,保证锁文件与环境一致。
锁文件与同步 #
uv.lock 记录了所有依赖(包括间接依赖)的精确版本和哈希值,应当提交到版本库。
| 命令 | 作用 |
|---|---|
uv lock |
根据 pyproject.toml 重新生成锁文件 |
uv sync |
按锁文件安装依赖,并删除多余的包 |
uv sync --locked |
锁文件过期时直接报错,适合 CI |
uv sync --no-dev |
不安装开发依赖,适合生产环境 |
运行命令 #
uv run 会先确保环境与锁文件一致,再在虚拟环境中执行命令,无需手动激活 .venv:
uv run python main.py
uv run pytest -q
配置镜像源 #
在国内网络环境下,可以在 pyproject.toml 中指定默认索引:
[[tool.uv.index]]
name = "tencent"
url = "https://mirrors.cloud.tencent.com/pypi/simple"
default = true
警告
锁文件会记录包的下载地址。更换索引后需要重新执行 uv lock,否则 uv sync --locked 会因为锁文件不一致而失败。
在 Docker 中使用 #
构建镜像时,先复制依赖声明安装依赖,再复制源码,可以充分利用构建缓存:
FROM python:3.14-slim
WORKDIR /app
RUN pip install uv
COPY pyproject.toml uv.lock ./
RUN uv sync --locked --no-dev --no-install-project
COPY . .
RUN uv sync --locked --no-dev
命令速查 #
-
uv init创建项目 -
uv add/uv remove管理依赖 -
uv sync同步环境 -
uv run运行命令 -
uv python pin固定 Python 版本(按需使用)