Debian 上 Python 依赖管理的最佳实践
一 管理思路与工具选择
- 使用系统包管理器 APT 安装与系统集成的库（包名通常为 python3-<库名>），可获得稳定、与系统其它组件一致的依赖与更新节奏。适合运维与系统级场景。
- 使用 pip 管理项目第三方库，灵活、版本新，适合开发与快速迭代。
- 使用 venv/virtualenv 为每个项目创建隔离环境，避免不同项目间的版本冲突。
- 使用 requirements.txt 记录依赖；复杂项目可用 pip-tools（pip-compile/pip-sync） 或 Poetry 做可重复构建与锁定版本。
二 快速上手流程
- 1）准备环境
- 更新索引并安装基础工具：
sudo apt update && sudo apt install -y python3 python3-pip python3-venv
- 2）创建并激活虚拟环境
- python3 -m venv .venv
- source .venv/bin/activate
- 3）在虚拟环境内用 pip 安装依赖
- pip install requests flask
- 4）导出与复现依赖
- pip freeze > requirements.txt
- 在新环境：pip install -r requirements.txt
- 5）退出虚拟环境
三 常用操作速查表
| 场景 |
命令示例 |
| APT 安装系统库 |
sudo apt install python3-requests |
| APT 搜索/卸载 |
apt search python3-；sudo apt remove python3- |
| 查看已装系统包 |
dpkg -l |
| pip 安装/升级/卸载 |
pip install ；pip install -U ；pip uninstall |
| 列出/查看包信息 |
pip list；pip show |
| 生成/安装 requirements |
pip freeze > requirements.txt；pip install -r requirements.txt |
| venv 创建/激活/退出 |
python3 -m venv .venv；source .venv/bin/activate；deactivate |
| pip-tools 锁定/同步 |
pip-compile requirements.in；pip-sync requirements.txt |
| Poetry 初始化/加依赖/安装 |
poetry init；poetry add ；poetry install |
四 进阶与常见问题
- 使用可重复依赖
- 直接 “pip freeze” 会包含间接依赖，环境重建时可能不一致。推荐：
- 用 pip-tools：在 requirements.in 写直接依赖 → pip-compile 生成带哈希的锁定文件 requirements.txt → 用 pip-sync 精确同步环境。
- 或用 Poetry：poetry add 管理依赖，poetry.lock 保证可复现构建与开发/生产一致性。
- 避免污染系统 Python
- 开发时一律在 虚拟环境 内使用 pip；不要对系统 Python 直接 “sudo pip install”。
- 处理编译型依赖的系统库
- 某些包（如数据库驱动）需要系统头文件与库，先装系统依赖再 pip 安装，例如：
sudo apt install libmysqlclient-dev libmariadb-dev-compat libssl-dev
pip install mysqlclient
- 版本过旧或需要新版
- Debian 仓库版本通常较稳但偏旧；开发可优先用虚拟环境 + pip；若必须升级系统 Python，请遵循发行版升级策略或使用独立工具链（如 pyenv/容器）隔离风险。