python依赖管理需用虚拟环境隔离、pyproject.toml统一声明、锁文件固化版本。推荐venv/conda/poetry，禁用全局pip install；锁文件必须提交，排查按python路径→环境→pip list→pip show→pipdeptree顺序进行。
Python版本冲突和依赖管理问题，核心在于隔离环境、明确约束、分层控制。不靠“全局升级”或“硬删包”，而是用工具链建立可复现、可迁移的依赖边界。
用虚拟环境彻底隔离Python解释器与包
不同项目可能依赖不同Python版本（如3.8跑旧系统、3.11跑新特性），也常需同一Python下多套互斥依赖（如Django 4.x vs 5.x）。直接在系统级pip install必然引发冲突。
- 推荐工具：venv（标准库，轻量）、conda（支持跨语言+Python多版本）、poetry（集成虚拟环境+依赖锁+打包）
-
关键操作：每个项目根目录执行
python -m venv .venv，激活后所有pip安装仅作用于该环境 -
注意：不要把
.venv提交到Git；在.gitignore中加入.venv/、venv/、env/
用pyproject.toml统一声明依赖与构建配置
替代过时的setup.py和requirements.txt混合管理方式。现代Python项目应以pyproject.toml为唯一源，定义运行依赖、开发依赖、构建系统和打包行为。
- 最小结构示例：
-
优势：语义化版本约束（
>=、、<code>~）、可选依赖分组、构建逻辑标准化
[build-system] requires = ["setuptools>=45", "wheel", "setuptools_scm[toml]>=6.2"] build-backend = "setuptools.build_meta" [project] name = "myapp" version = "0.1.0" dependencies = [ "requests>=2.28.0,<3.0.0", "click>=8.0.0" ] [project.optional-dependencies] dev = ["pytest>=7.0.0", "black>=23.0.0"]
用依赖锁文件保障环境一致性
pyproject.toml只写范围约束，实际安装时版本仍可能漂移（如requests>=2.28.0下次装到2.32.0，引发兼容问题）。必须生成锁定文件固化全部传递依赖。
立即学习“Python免费学习笔记（深入）”；
-
poetry用户：运行
poetry lock生成poetry.lock；CI/部署时用poetry install（而非poetry add）确保完全一致 -
pip用户：用
pip-compile（来自pip-tools）：先写requirements.in，再运行pip-compile requirements.in生成requirements.txt（含精确版本+哈希） -
关键原则：锁文件必须提交到Git；开发/测试/生产全部基于锁文件还原，而非重新解析
pyproject.toml
版本冲突排查：从报错日志反向定位
当出现ImportError、AttributeError或pkg_resources.DistributionNotFound，别急着重装，按顺序检查：
- 确认当前Python路径：
which python或python -c "import sys; print(sys.executable)" - 确认已激活正确虚拟环境：
python -m pip list查看实际安装的包及其版本 - 查冲突根源：
pip show package_name看它被谁依赖、安装位置；用pipdeptree --reverse --packages 包名找出谁拉入了不兼容版本 - 临时验证：在干净虚拟环境中仅装报错模块，观察是否复现——若不复现，说明是依赖叠加导致的隐式冲突
