为什么要写这篇

深度学习环境最容易踩坑的点，不是模型本身，而是依赖冲突、CUDA 版本不匹配和跨机器复现失败。
这篇的目标是给出一套可落地的实践：

  1. 用 Conda 管理 Python 与底层二进制依赖。
  2. 用 uv 管理项目级 Python 包与锁文件。
  3. 用一组验证与监控工具确保环境可用、可复现、可排障。

依赖文件怎么选

一般项目里常见三类文件：

  1. requirements.txt：传统 pip 依赖清单，简单直接。
  2. environment.yml：Conda 环境定义，适合包含 Python 之外的依赖。
  3. pyproject.toml + uv.lock：现代化依赖管理与锁定，团队协作更稳定。

安装命令示例：

pip install -r requirements.txt
# 或者
conda env create -f environment.yml
# 如果你使用 uv
uv sync

Conda 相关命令

1) 环境创建与激活

# 创建环境（推荐固定主版本）
conda create -n dl python=3.11 -y

# 激活环境
conda activate dl

# 查看当前环境列表
conda env list

# 查看当前环境信息
conda info

# 删除环境
conda remove -n dl --all -y

2) 包管理

# 安装包
conda install numpy pandas -y

# 指定频道安装
conda install pytorch torchvision torchaudio -c pytorch -y

# 更新某个包
conda update numpy -y

# 卸载包
conda remove pandas -y

3) 环境导出与复现

# 导出完整环境（包含精确版本）
conda env export > environment.yml

# 按文件恢复环境
conda env create -f environment.yml

4) 配置与加速

# 查看当前 channels 配置
conda config --show channels

# 设置严格频道优先级，减少不必要冲突
conda config --set channel_priority strict

# 添加 conda-forge（按需）
conda config --add channels conda-forge

# 查看配置来源
conda config --show-sources

# 清理缓存
conda clean --all -y

5) 回滚与强复现

# 查看环境历史版本
conda list --revisions

# 回滚到指定修订版本
conda install --revision 3

# 仅导出手动安装过的依赖（轻量复现）
conda env export --from-history > environment.min.yml

# 导出显式包列表（强一致复现）
conda list --explicit > spec-file.txt

# 用显式包列表创建环境
conda create -n dl-repro --file spec-file.txt

# 删除环境
conda remove -n dl --all -y

6) 常见问题

  1. 依赖求解很慢：优先减少频道数量，或改用 mamba/micromamba。
  2. 冲突频繁：先固定 Python 主版本，再逐步安装核心包。
  3. GPU 包异常：优先查 PyTorch 官方版本矩阵，再安装对应 CUDA 版本。

uv 相关命令

1) 项目初始化与依赖安装

# 初始化项目（生成 pyproject.toml）
uv init

# 添加运行时依赖
uv add torch torchvision torchaudio

# 添加开发依赖
uv add --dev pytest ruff

# 同步依赖到当前环境
uv sync

2) 依赖维护

# 删除依赖
uv remove torch

# 锁定依赖
uv lock

# 按锁文件同步，保证跨机器一致
uv sync --frozen

# 导出 requirements.txt 风格锁定文件
uv export --format requirements-txt > requirements.lock.txt

3) Python 与诊断命令

# 查看可用 Python 版本
uv python list

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

# 在 uv 管理上下文中运行命令
uv run python -V

# 查看依赖树
uv tree

# 检查依赖是否存在元数据冲突
uv pip check

# 清理 uv 缓存
uv cache prune

4) 与 Conda 搭配的建议

推荐分层管理：

  1. Conda 管 Python 版本和底座依赖。
  2. uv 管项目依赖和锁文件。

这样做的优点是：安装快、冲突少、协作复现更稳定。

推荐工作流（Conda + uv）

# 1) 创建并激活基础环境
conda create -n dl python=3.11 -y
conda activate dl

# 2) 初始化项目并安装依赖
uv init
uv add torch torchvision torchaudio
uv add --dev ruff pytest
uv sync

# 3) 验证环境
python -c "import torch; print(torch.__version__); print(torch.cuda.is_available())"

# 4) 锁定依赖并提交
uv lock

一些好用的工具类

这里推荐的是一些管理与系统检测常用工具：

  1. GPU 状态检测
    • gpustat：轻量级命令行工具，快速查看显存与进程。
    • nvitop：更现代的 GPU 监控界面，Windows/Linux 都更友好。
  2. 依赖排障
    • pipdeptree：查看依赖树，定位冲突来源。
  3. 代码质量
    • ruff：高性能 Lint 与格式检查工具。
    • pre-commit：提交前自动执行检查，减少低级错误。
  4. 实验追踪
    • wandb 或 mlflow：记录参数、指标、模型版本，便于对比实验结果。

对应安装命令示例：

# GPU 监控
pip install gpustat nvitop

# 依赖排障
pip install pipdeptree

# 代码质量
pip install ruff pre-commit

# 实验追踪（二选一或都装）
pip install wandb mlflow

GPU 与环境诊断命令

# 查看 GPU 与驱动状态
nvidia-smi

# 查看 CUDA 工具链版本（已安装时可用）
nvcc --version

# 检查 PyTorch 与 CUDA 可用性
python -c "import torch; print(torch.__version__); print(torch.version.cuda); print(torch.cuda.is_available())"

# 输出 PyTorch 环境诊断信息
python -m torch.utils.collect_env

依赖与质量校验命令

# 检查已安装包的依赖一致性
pip check

# 输出依赖树并在冲突时返回非零状态
pipdeptree --warn fail

# 代码检查
ruff check .

# 运行 pre-commit 全量检查
pre-commit run --all-files

最小排障清单

  1. 先确认 Python 版本与项目要求一致。
  2. 再确认 CUDA、驱动、PyTorch 三者匹配。
  3. 如果 import 失败，先看依赖冲突，再看系统动态库。
  4. 对团队项目，优先使用锁文件而不是手动安装。

参考

  1. Conda 文档：https://docs.conda.io/
  2. uv 文档：https://docs.astral.sh/uv/
  3. PyTorch 安装指引：https://pytorch.org/get-started/locally/
  4. NVIDIA 驱动与 CUDA：https://developer.nvidia.com/cuda-downloads