用 uv 管理 Python 项目

uv 把虚拟环境、依赖管理、锁文件和 Python 版本管理整合到一个工具中,本文记录日常开发中最常用的工作流。

Python 约 2 分钟 450 字
本文目录
  1. 初始化项目
  2. 管理依赖
  3. 锁文件与同步
  4. 运行命令
  5. 配置镜像源
  6. 在 Docker 中使用
  7. 命令速查

uv 是用 Rust 编写的 Python 包与项目管理工具。它可以替代 pip、venv、pip-tools 和 pyenv 的大部分功能,而且速度非常快。

初始化项目 #

bash
uv init --package my-app
cd my-app

--package 会生成 src 布局的项目结构,适合需要打包或包含多个模块的项目:

text
my-app/
├── .python-version
├── README.md
├── pyproject.toml
└── src/
    └── my_app/
        └── __init__.py

.python-version 记录项目使用的 Python 版本。如果本机没有这个版本,uv 会自动下载。

管理依赖 #

bash
uv add fastapi uvicorn   # 添加运行时依赖
uv add --dev pytest      # 添加开发依赖
uv remove uvicorn        # 移除依赖

依赖会写入 pyproject.toml,同时更新 uv.lock:

toml
[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:

bash
uv run python main.py
uv run pytest -q

配置镜像源 #

在国内网络环境下,可以在 pyproject.toml 中指定默认索引:

toml
[[tool.uv.index]]
name = "tencent"
url = "https://mirrors.cloud.tencent.com/pypi/simple"
default = true

警告

锁文件会记录包的下载地址。更换索引后需要重新执行 uv lock,否则 uv sync --locked 会因为锁文件不一致而失败。

在 Docker 中使用 #

构建镜像时,先复制依赖声明安装依赖,再复制源码,可以充分利用构建缓存:

dockerfile
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 版本(按需使用)