⚡

Python依赖管理技能Skill dependency-manager

这个技能专注于使用UV、pip-tools和requirements.txt等工具来高效管理Python项目的依赖关系，包括依赖安装、版本控制、冲突解决、虚拟环境设置以及CI/CD集成，旨在提高开发效率和项目可维护性。关键词：Python依赖管理、UV工具、pip-tools、requirements.txt、依赖解析、虚拟环境、CI/CD、版本控制、依赖冲突解决。

DevOps 0 次安装 0 次浏览 更新于 3/9/2026

name: 依赖管理器 description: 使用 UV、pip-tools 或 requirements.txt 管理 Python 依赖。适用于设置依赖管理、解决冲突或选择 UV、pip-tools 和 requirements.txt 工作流时使用。

依赖管理器

使用 UV、pip-tools 或 requirements.txt 管理 Python 项目依赖。

快速开始

选择 UV 用于新项目（快速、现代），pip-tools 用于现有 pip 工作流，或 requirements.txt 用于简单项目。

指令

选择工具

UV - 快速、现代的 Python 包管理器（推荐）：

  • 极快的依赖解析（比 pip 快 10-100 倍）
  • 自动虚拟环境管理
  • 可作为 pip 和 pip-tools 的替代品
  • 支持锁文件 uv.lock
  • 最佳适用：所有项目，特别是新项目

pip-tools - 轻量级、兼容 pip 的工作流：

  • 从 requirements.in 生成锁文件
  • 与现有 pip 工作流兼容
  • 对项目结构改动最小
  • 最佳适用：现有项目、使用 pip 的 CI/CD、逐步采用

requirements.txt - 简单、通用：

  • 直接 pip install
  • 无需额外工具
  • 无锁文件（除非手动维护）
  • 最佳适用：简单脚本、最小依赖、快速原型

UV 设置（推荐）

安装 UV：

curl -LsSf https://astral.sh/uv/install.sh | sh
# 或使用 pip
pip install uv

初始化新项目：

uv init my-project
cd my-project

添加依赖：

# 运行时依赖
uv add requests

# 开发依赖
uv add --dev pytest

# 带版本约束
uv add "requests>=2.28.0,<3.0.0"

安装依赖：

uv sync

更新依赖：

# 更新所有
uv lock --upgrade

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

移除依赖：

uv remove requests

显示依赖树：

uv tree

导出到 requirements.txt：

uv pip compile pyproject.toml -o requirements.txt

在虚拟环境中运行命令：

uv run python script.py
uv run pytest

pip-tools 设置

安装 pip-tools：

pip install pip-tools

创建 requirements.in：

# requirements.in
requests>=2.28.0
flask>=2.0.0

创建 requirements-dev.in：

# requirements-dev.in
-c requirements.txt  # 约束到生产版本
pytest>=7.0.0
black>=23.0.0
mypy>=1.0.0

编译锁文件：

# 编译生产依赖
pip-compile requirements.in

# 编译开发依赖
pip-compile requirements-dev.in

这会生成带固定版本的 requirements.txt 和 requirements-dev.txt。

安装依赖：

pip-sync requirements.txt requirements-dev.txt

更新依赖：

# 更新所有
pip-compile --upgrade requirements.in

# 更新特定包
pip-compile --upgrade-package requests requirements.in

添加新依赖：

  1. 添加到 requirements.in
  2. 运行 pip-compile requirements.in
  3. 运行 pip-sync requirements.txt

requirements.txt 工作流

创建 requirements.txt：

pip freeze > requirements.txt

安装依赖：

pip install -r requirements.txt

分离开发依赖：

创建 requirements-dev.txt：

-r requirements.txt
pytest>=7.0.0
black>=23.0.0

安装：

pip install -r requirements-dev.txt

版本约束

UV/PEP 621 语法（pyproject.toml）：

[project]
dependencies = [
    "requests>=2.28.0,<3.0.0",  # 范围
    "flask~=2.0.0",              # 兼容发布
    "django>=3.2,<4.0",          # 范围
    "numpy==1.24.0",             # 精确版本
]

pip 语法（requirements.in 或 requirements.txt）：

requests>=2.28.0,<3.0.0
flask~=2.0.0
django>=3.2,<4.0
numpy==1.24.0
pandas

约束操作符：

  • ==：精确版本
  • >=, <=：最小/最大版本
  • ~=：兼容发布（补丁更新）
  • ,：组合约束（AND）

依赖组

UV/PEP 621 组：

[project.optional-dependencies]
dev = ["pytest>=7.0.0", "black>=23.0.0"]
docs = ["sphinx>=5.0.0"]
test = ["coverage>=7.0.0"]

安装特定组：

uv sync --extra dev
uv sync --extra docs
uv sync --all-extras

pip-tools 方法：

创建单独的 .in 文件：

  • requirements.in - 生产
  • requirements-dev.in - 开发
  • requirements-test.in - 测试
  • requirements-docs.in - 文档

解决冲突

使用 UV：

  1. 检查冲突：

    uv add package-name
# UV 会显示冲突如果存在

  2. 更新 pyproject.toml 中的约束：

    [project]
dependencies = [
    "package-a>=2.0.0",  # 放宽约束
    "package-b>=3.0.0",
]

  3. 强制解析：

    uv lock
uv sync

使用 pip-tools：

  1. 检查冲突：

    pip-compile requirements.in
# 会显示解析错误

  2. 调整 requirements.in 中的约束：

    package-a>=2.0.0  # 放宽约束
package-b>=3.0.0

  3. 重新编译：

    pip-compile requirements.in

常见冲突模式：

  • 传递依赖冲突：两个包需要第三个包的不兼容版本

    • 解决方案：更新一个或两个包，或放宽约束

  • Python 版本冲突：包需要比项目支持的新 Python 版本

    • 解决方案：升级 Python 版本或找到替代包

  • 平台特定冲突：包在当前平台不可用

    • 解决方案：使用平台标记或可选依赖

平台特定依赖

UV/PEP 621：

[project]
dependencies = [
    "pywin32>=305; sys_platform == 'win32'",
    "python-daemon>=2.3; sys_platform == 'linux'",
]

pip：

pywin32>=305; sys_platform == 'win32'
python-daemon>=2.3; sys_platform == 'linux'

可选依赖

UV/PEP 621：

[project.optional-dependencies]
aws = ["boto3>=1.26.0"]
all = ["boto3>=1.26.0"]  # 包含所有可选依赖

安装：

uv sync --extra aws
uv pip install package-name[aws]

虚拟环境

UV（自动）：

# UV 自动创建和管理虚拟环境
uv sync
uv run python script.py
source .venv/bin/activate  # 需要时手动激活

pip-tools（手动）：

# 创建虚拟环境
python -m venv venv

# 激活
source venv/bin/activate  # Linux/Mac
venv\Scripts\activate     # Windows

# 安装
pip-sync requirements.txt

requirements.txt（手动）：

python -m venv venv
source venv/bin/activate
pip install -r requirements.txt

CI/CD 集成

UV 在 CI（推荐）：

# .github/workflows/test.yml
- name: 安装 UV
  run: curl -LsSf https://astral.sh/uv/install.sh | sh

- name: 安装依赖
  run: uv sync

- name: 运行测试
  run: uv run pytest

pip-tools 在 CI：

- name: 安装依赖
  run: |
    pip install pip-tools
    pip-sync requirements.txt requirements-dev.txt

- name: 运行测试
  run: pytest

requirements.txt 在 CI：

- name: 安装依赖
  run: pip install -r requirements.txt

- name: 运行测试
  run: pytest

迁移策略

从 requirements.txt 到 UV：

  1. 初始化 UV 项目：

    uv init --no-readme

  2. 导入依赖：

    # 从 requirements.txt 添加每个依赖
cat requirements.txt | grep -v "^#" | xargs -I {} uv add {}

  3. 分离开发依赖：

    uv add --dev pytest black mypy

  4. 测试：

    uv sync
uv run pytest

从 requirements.txt 到 pip-tools：

  1. 重命名 requirements.txt：

    mv requirements.txt requirements.in

  2. 编译锁文件：

    pip-compile requirements.in

  3. 创建开发需求：

    echo "-c requirements.txt" > requirements-dev.in
echo "pytest" >> requirements-dev.in
pip-compile requirements-dev.in

  4. 测试：

    pip-sync requirements.txt requirements-dev.txt

从 pip-tools 到 UV：

  1. 创建 pyproject.toml：

    uv init --no-readme

  2. 从 requirements.in 导入：

    cat requirements.in | grep -v "^#" | grep -v "^-" | xargs -I {} uv add {}

  3. 测试：

    uv sync

常见模式

带有共享依赖的单仓库

UV 工作区：

# 根 pyproject.toml
[tool.uv.workspace]
members = ["packages/*"]

# packages/package1/pyproject.toml
[project]
name = "package1"
dependencies = ["requests>=2.28.0"]

# packages/package2/pyproject.toml
[project]
name = "package2"
dependencies = ["requests>=2.28.0"]

pip-tools 方法：

# shared-requirements.in
requests>=2.28.0

# package1/requirements.in
-c ../shared-requirements.txt
flask>=2.0.0

# package2/requirements.in
-c ../shared-requirements.txt
django>=4.0.0

锁文件最佳实践

提交锁文件：

  • uv.lock - 总是提交
  • requirements.txt（从 pip-compile） - 总是提交
  • requirements.txt（从 pip freeze） - 考虑提交

定期更新：

# UV
uv lock --upgrade

# pip-tools
pip-compile --upgrade requirements.in

更新后验证：

# 运行测试
uv run pytest

# 检查安全问题
pip-audit

故障排除

UV 锁耗时太长：

  • UV 通常非常快；如果慢，检查网络问题
  • 使用 uv lock --offline 使用缓存包
  • 检查循环依赖

pip-compile 失败冲突：

  • 放宽 requirements.in 中的版本约束
  • 使用 pip-compile --resolver=backtracking 进行更好解析
  • 检查不兼容的传递依赖

依赖未找到：

  • 验证包名（检查 PyPI）
  • 检查 Python 版本兼容性
  • 确保正确的索引 URL（用于私有包）
  • 使用 UV：uv pip install --index-url https://custom-index.com package

虚拟环境问题：

  • 删除并重新创建：rm -rf .venv && uv sync
  • 检查 Python 版本匹配项目需求
  • UV 自动管理虚拟环境

过时依赖：

  • 检查：uv tree --outdated 或 pip list --outdated
  • 小心更新，每次主要更新后测试
  • 使用 uv lock --upgrade --dry-run 预览更改