如何用 pip-tools 锁定 Python 依赖新手完整上手指南【免费下载链接】pip-toolsA set of tools to keep your pinned Python dependencies fresh.项目地址: https://gitcode.com/gh_mirrors/pi/pip-tools深夜加班同事甩给你一行命令pip install -r requirements.txt。装完一跑报错。你查环境、对版本、翻文档折腾两小时才发现——罪魁祸首是某个依赖悄悄升级了连带一堆间接依赖一起变。这个场景凡是没认真锁定过 Python 依赖的人都遇到过。pip-tools正是为解决这个问题而生它用pip-compile和pip-sync两个命令帮你把散装依赖变成一份精确锁定的清单让昨天能跑今天必能跑成为常态。pip-tools 的自我定位很直白A set of tools to keep your pinned Python dependencies fresh——锁定依赖同时让它们保持新鲜。下面我们从一个真实工作流出发把它完整跑一遍。3 分钟跑起来pip-tools 安装教程与第一条命令先做最短路实验你只需要三步。第一步准备一个干净的虚拟环境新手提示虚拟环境是每个项目独立的 Python 小天地避免包互相污染$ python -m venv venv $ source venv/bin/activate第二步安装 pip-tools(venv) $ pip install pip-tools装好后就多出了pip-compile和pip-sync两个命令。你可以用pip-compile --help快速验证是否安装成功。第三步写一个依赖清单并生成锁定文件新建一个requirements.in只写你直接用到的依赖先不写版本# requirements.in django然后执行(venv) $ pip-compile requirements.in神奇的事情发生了——目录里多出一个requirements.txt里面不仅锁定了 django 的版本连它背后的asgiref、sqlparse等间接依赖也一并锁死每一条都带# via django注释告诉你我是被谁引进来的。提示pip-tools 必须安装并运行在项目的虚拟环境里这样生成的条件依赖比如按 Python 版本区分的包才能贴合你的真实环境。核心用法拆解三条主线从入门到落地了解了基本流程后我们把整个工作流拆成三条主线锁定 → 同步 → 自动化。主线一用 pip-compile 生成 requirements.txt锁定全量依赖这是整个工具的基石。核心思路是两套文件分工requirements.in你手写只声明顶层依赖宽泛、好维护比如django、requests2requirements.txt机器生成包含所有传递依赖的精确版本直接用于生产部署每次跑pip-compile它都会基于.in重新解析。值得注意的是如果发现现有的requirements.txt已经能满足要求它不会擅自改动——保持稳定是第一原则。想整体升级所有包加--upgrade想只升级某一个用--upgrade-package# 只把 django 升到最新 (venv) $ pip-compile --upgrade-package django # 整体升级但把 requests 限制在 3.0 以下 (venv) $ pip-compile --upgrade --upgrade-package requests3.0主线二用 pip-sync 同步依赖让环境与清单完全一致光有清单还不够环境里装的东西得和清单对得上。pip-sync做的事就是对账清单里有而环境没有的装上版本不对的升级/降级清单里没有而环境多余的卸载。(venv) $ pip-sync也可以一次同步多份清单(venv) $ pip-sync requirements.txt dev-requirements.txt⚠️ 注意pip-sync只适合配合pip-compile生成的清单使用。它会严格执行环境 清单把多余的东西直接卸载所以务必在专用虚拟环境里跑别拿它去同步你日常开发的大环境。另外它不会动pip、setuptools、pip-tools自身升级这些要用pip install -U。主线三把它变成自动化习惯让团队告别手工锁定依赖最怕的是只有你一个人在锁。两个常见的自动化落地点配合 pre-commit每次提交前自动重新编译清单一旦过期就拦截。示例配置repos: - repo: https://github.com/jazzband/pip-tools rev: 7.4.1 hooks: - id: pip-compile配合 CI在流水线里跑pip-sync用锁定的requirements.txt安装保证每次构建环境可复现。这样我本地能跑就不再是玄学任何机器装出来的环境都一样。进阶技巧让效率翻倍的 5 个小招1. 生成哈希校验防篡改--generate-hashes会为每个包生成 sha256 哈希pip install时按哈希校验安全性拉满(venv) $ pip-compile --generate-hashes requirements.in2. 分层约束生产一份、开发一份在dev-requirements.in第一行写-c requirements.txt开发依赖就会受生产清单约束两套清单不会打架# dev-requirements.in -c requirements.txt django-debug-toolbar3. 直接吃 pyproject.toml紧跟新标准新版 pip-tools 支持直接从pyproject.toml读取依赖还能用--extra单独锁定可选依赖组(venv) $ pip-compile --extra dev -o dev-requirements.txt pyproject.toml4. 不同 Python 版本各锁一份环境标记如sys_platform、python_version会让不同环境下锁定的包不同。建议在目标环境分别执行编译并用{环境}-requirements.txt命名区分。5. 多 Python 版本共存时用模块调用装了多个 Python 时用-m方式指定版本执行比裸命令更可控$ python3.11 -m piptools compile $ python3.11 -m piptools sync常见问题 FAQ新手最容易踩的 4 个坑Q1明明有新版本pip-compile 却死活不更新一句话结论现有的requirements.txt会被当作版本约束默认保持不变。解决命令加--upgrade或--upgrade-package 包名强制刷新。Q2pip-sync 把我环境里的包卸载了一句话结论它本来就保证环境 清单多出来的都会被清掉。解决命令只在专用虚拟环境里跑且确保清单由pip-compile生成。Q3生成的 requirements.txt 拿到别人电脑上装就失败一句话结论不同 Python 版本/操作系统解析出的依赖可能不同。解决命令在目标环境里重新执行一次pip-compile按环境分别锁定。Q4pip-sync 为什么不管 pip 和 setuptools 的升级一句话结论这是设计如此防止误伤工具链自身。解决命令用pip install --upgrade pip-tools手动升级。写在最后一句话总结pip-tools 用一份手写清单 一份机器锁定清单 两个命令把你的 Python 依赖从碰运气变成可复现值得写进每个项目的标准流程。想深入挖细节项目文档就在仓库里推荐从这几处入手完整参考手册docs/reference/pip-compile 参数全解docs/reference/pip-compile.mdpip-sync 参数全解docs/reference/pip-sync.md官方入门说明docs/index.md从今天起让你的每个 Python 项目都配上一份锁定的 requirements.txt 吧。【免费下载链接】pip-toolsA set of tools to keep your pinned Python dependencies fresh.项目地址: https://gitcode.com/gh_mirrors/pi/pip-tools创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考