安装方式：

pip install -r requirements.txt

问题所在：无法区分顶层依赖和传递依赖，没有锁定机制，团队协作时经常出现"在我机器上能跑"的问题。

2.2 pip freeze的局限性

pip freeze > requirements.txt

pip freeze会导出所有已安装的包（包括传递依赖），导致：

2.3 setup.py与pyproject.toml

现代Python项目的标准配置方式是pyproject.toml：

[project]
name = "my-project"
version = "1.0.0"
requires-python = ">=3.10"
dependencies = [
    "flask>=3.0",
    "requests>=2.31",
    "sqlalchemy>=2.0",
]

[project.optional-dependencies]
dev = [
    "pytest>=7.0",
    "ruff>=0.4",
    "mypy>=1.0",
]

三、现代工具链全面对比

3.1 pip-tools：确定性构建

pip-tools通过分离顶层依赖和锁定文件来解决确定性问题：

# 安装
pip install pip-tools

# 定义顶层依赖（只列出直接需要的包）
# requirements.in
flask>=3.0
requests>=2.31

# 生成锁定文件（包含所有传递依赖的精确版本）
pip-compile requirements.in

# 锁定文件 requirements.txt 自动生成，包含完整依赖树和hash

这种方式的优势：

3.2 Poetry：全生命周期管理

Poetry提供从创建项目到发布包的全流程管理：

# 安装
pipx install poetry

# 创建新项目
poetry new my-project
cd my-project

# 添加依赖（自动解析版本，更新lock文件）
poetry add flask@latest
poetry add --group dev pytest ruff

# 安装所有依赖（包括lock文件中的）
poetry install

# 更新依赖
poetry update --lock

# 运行命令
poetry run python app.py

poetry.lock文件记录了完整的依赖树，包含精确的-versions、hash和来源信息，确保团队成员和环境之间的完全一致性。

3.3 PDM：PEP 621的践行者

PDM（Python Development Master）是一个相对年轻但设计精良的工具，它原生支持PEP 621标准：

# 安装
pipx install pdm

# 初始化项目
pdm init

# 添加依赖
pdm add flask
pdm add -dG dev pytest ruff

# 安装
pdm install

# 运行
pdm run python app.py

PDM的特点：

3.4 uv：Rust重写的极速工具

uv是由Astral团队用Rust编写的Python包管理器，目标是替代pip、pip-tools和venv的组合：

# 安装（推荐方式）
curl -LsSf https://astral.sh/uv/install.sh | sh

# 或
pipx install uv

# 创建虚拟环境
uv venv .venv

# 添加依赖并生成lock文件
uv add flask requests sqlalchemy

# 同步依赖
uv sync

# 编译锁定文件（不安装）
uv lock

# 运行命令
uv run python app.py

# pip兼容接口
uv pip install flask
uv pip compile requirements.in -o requirements.txt

四、uv的工程化实战

4.1 uv的性能优势

uv用Rust重写了包解析和下载的核心逻辑，性能优势显著：

实际测试数据（冷缓存首次安装Flask项目，~30个依赖）：

4.2 项目级配置

pyproject.toml中 uv 的完整配置：

[project]
name = "my-web-app"
version = "2.0.0"
requires-python = ">=3.11"
dependencies = [
    "fastapi>=0.110",
    "uvicorn[standard]>=0.29",
    "pydantic>=2.7",
    "httpx>=0.27",
]

[project.optional-dependencies]
dev = [
    "pytest>=8.0",
    "pytest-asyncio>=0.23",
    "ruff>=0.4",
    "mypy>=1.10",
]
docs = [
    "mkdocs>=1.6",
    "mkdocs-material>=9.5",
]

[tool.uv]
dev-dependencies = [
    "ipython>=8.0",
    "ipdb>=0.13",
]

[tool.uv.sources]
# 指定私有源
private-lib = { git = "https://github.com/my-org/private-lib.git", tag = "v1.0" }
internal-tool = { path = "../internal-tool", editable = true }

4.3 uv.lock锁定文件

uv生成的uv.lock文件是跨平台的确定性依赖方案：

# 严格按lock文件安装
uv sync --frozen

# 更新特定包
uv lock --upgrade-package flask

# 更新所有包
uv lock --upgrade

# 验证lock文件一致性
uv lock --check

4.4 多Python版本管理

uv内置了Python版本管理功能：

# 安装指定Python版本
uv python install 3.11 3.12 3.13

# 列出已安装版本
uv python list

# 为项目指定Python版本
uv python pin 3.12

# 使用特定Python版本创建环境
uv venv --python 3.12 .venv

4.5 CI/CD集成

uv在CI环境中表现出色，因为它可以跳过虚拟环境创建和大量重复下载：

# .github/workflows/ci.yml
name: CI
on: [push]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install uv
        uses: astral-sh/setup-uv@v3
        with:
          enable-cache: true
          cache-dependency-glob: "uv.lock"

      - name: Set up Python
        run: uv python install

      - name: Install dependencies
        run: uv sync --frozen --all-extras

      - name: Run tests
        run: uv run pytest

      - name: Lint
        run: uv run ruff check .

缓存uv.lock文件后，CI安装可以从几分钟缩短到十几秒。

4.6 Docker多阶段构建优化

在Docker中使用uv可以显著减小镜像体积和构建时间：

FROM python:3.12-slim as builder

# 安装uv
COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/

WORKDIR /app
COPY pyproject.toml uv.lock ./

# 导出依赖到临时目录（利用uv的缓存加速层）
RUN uv sync --frozen --no-install-project --no-dev

FROM python:3.12-slim as runtime

WORKDIR /app

# 仅复制必要的依赖，不包含构建工具
COPY --from=builder /app/.venv /app/.venv

COPY . .

ENV PATH="/app/.venv/bin:$PATH"
CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]

五、团队协作最佳实践

5.1 锁定文件的版本控制

所有锁定文件必须纳入版本控制：

项目根目录/
├── pyproject.toml       # 依赖声明
├── uv.lock              # 锁定文件（必须提交）
├── .python-version      # Python版本（必须提交）
└── .gitignore           # 忽略.venv和__pycache__

5.2 依赖分层策略

按使用场景分层管理依赖：

[project]
dependencies = [
    # 运行时核心依赖（最少集合）
    "fastapi",
    "pydantic",
    "sqlalchemy",
]

[project.optional-dependencies]
# 测试相关
test = ["pytest", "pytest-asyncio", "httpx"]
# 代码质量
lint = ["ruff", "mypy"]
# 文档相关
docs = ["mkdocs", "mkdocs-material"]
# 开发便利
dev = ["ipython", "ipdb", "rich"]
# 全部开发依赖
all = ["my-project[test,lint,dev]"]

5.3 版本约束策略

合理的版本约束避免"依赖地狱"：

5.4 安全扫描

定期审计依赖安全性：

# uv原生支持
uv audit

# 或使用safety
pipx install safety
safety check -r requirements.txt

# 或pip-audit
pipx install pip-audit
pip-audit

六、迁移指南：从旧工具到uv

6.1 从venv + pip迁移

# 1. 在项目根目录初始化uv
cd your-project
uv init

# 2. 将requirements.txt中的依赖导入uv
uv add $(cat requirements.txt | grep -v "^#" | tr '\n' ' ')

# 3. 清理旧文件
rm -rf .venv requirements.txt
rm venv/  # 如果存在

# 4. 创建新环境
uv venv

# 5. 同步依赖
uv sync

6.2 从Poetry迁移

# uv可以从pyproject.toml读取Poetry配置
# 1. 移除Poetry特有标记
sed -i '/\[tool.poetry\]/,/^$/d' pyproject.toml

# 2. 如果依赖在[tool.poetry.dependencies]中，需要手动移到[project.dependencies]
# 因为uv遵循PEP 621标准格式

# 3. 清理Poetry的虚拟环境
poetry env remove --all

# 4. 使用uv初始化
uv init
uv sync

6.3 迁移检查清单

七、总结

Python的依赖管理工具链已经进入了uv时代。相比传统的pip+venv+pip-tools组合，uv以Rust的极致性能、统一的命令行接口和完善的锁定机制，成为2025-2026年Python工程化的最佳选择。

对于新项目，建议直接使用uv init开始。对于已有项目，迁移到uv通常只需要一个下午的工作量，但带来的收益——更快的构建、确定性的环境、统一的工具链——将在整个项目生命周期中持续产生价值。

关键选择建议：

工具只是手段，确定性和可重现性才是目的。无论选择哪种工具，关键是确保团队成员使用相同版本的同一套依赖，从源头消灭"在我机器上能跑"的问题。