简介面向 Python 开发者的 pip 21.3.1 官方源码包适合需要深入理解包管理器实现机制、进行离线安装或二次定制的读者。该版本包含 install、uninstall、show、list 等常用命令的完整实现也覆盖依赖约束、虚拟环境、镜像源与安全选项等核心逻辑可作为学习 Python 打包分发原理的参考材料。包体共 538 个文件以 402 个 Python 源码文件为主另有 67 个 RST 文档、17 个 Markdown 说明、15 个许可证文件及若干 cfg、toml、pem 等配置类文件整体结构清晰便于按模块查阅压缩包大小约 1.65MB轻量而完整。已有 1593 人学习使用。通过分析源码可掌握 pip 的安装升级流程、版本解析与依赖处理思路也可直接提取其中工具脚本用于自定义包管理场景对提升 Python 工程化能力有直接帮助。1. 拿到 pip-21.3.1.tar.gz先别急着装如果你搜到这个文件名大概率是遇到了下面三种情况之一要么是手动从 PyPI 官网把 pip 源码包下载下来了要么是在内网离线环境里需要自己装 pip要么就是跟着某篇教程操作结果教程给的链接直接指向了这个 tar.gz 文件。不管是哪种先把结论放在前面在绝大多数情况下你根本不需要手动安装 pip-21.3.1.tar.gz直接用官方推荐的引导命令python -m ensurepip或者get-pip.py就能搞定而且更省事、更不容易踩坑。那为什么网上还有这么多人在找这个包因为 pip 从 21.3 开始变化很大很多老教程、老脚本里写死了版本号导致后来的人照抄时被带偏。再加上 pip 21.3.1 恰好处于一个“旧版能用、新版更好”的过渡期很多人为了兼容旧项目、旧依赖锁文件就非得用这个版本不可。我自己也有一台内网机器常年不连外网系统自带的 Python 版本又老pip 装不上、装上了又用不了的情况见过太多次了。所以这篇文章就围绕 pip-21.3.1.tar.gz 这个文件把“什么时候需要它、怎么正确装它、装上之后怎么用、遇到问题怎么排查”整个链路讲透。适合谁看三种人一是刚入门 Python、被各种报错折磨的新手搞不清 pip 到底怎么回事二是需要在离线或内网环境部署 Python 环境的运维和开发三是项目依赖锁定在旧版本 pip、被迫手动装包的老项目维护者。不管你是哪种这篇文章都会给你一套可以直接照做的方案。2. 先搞清楚pip 到底是个什么东西在动手装之前我建议你先花两分钟把 pip 的本质搞清楚不然以后遇到各种奇怪问题还是会一脸懵。2.1 pip 是什么它和 Python 是什么关系pip 是 Python 官方的包管理工具全称叫 Pip Installs Packages作用是帮你从 PyPIPython Package IndexPython 官方软件包仓库下载、安装、卸载、管理第三方库。你可以把它理解成手机上的应用商店Python 是手机系统pip 是应用商店各种第三方库就是 App。你想装一个 App不用自己去网上找安装包直接在应用商店里搜索安装就行pip 干的就是这件事。pip 本身也是用 Python 写的所以它也是一个 Python 包也可以被 pip 自己管理。这就出现了一个有点绕但很关键的点pip 可以升级 pip 自己。当你执行pip install --upgrade pip时本质上是把当前环境里的 pip 包替换成新版本。由于 pip 的版本迭代非常频繁PyPI 上每几个月就会发布一个或多个新版本所以网上的教程、Docker 镜像、CI 脚本里经常会看到“安装指定版本 pip”这类需求。2.2 pip 21.3.1 这个版本特殊在哪pip 21.3.1 发布于 2021 年 11 月属于 pip 21.3 系列的一个 bugfix 版本。这个版本之所以在网络上还有不小的存在感是因为它处在几个关键变化的节点上第一pip 21.3 是默认启用 PEP 660可编辑安装的新机制的首个大版本。简单说pip install -e .这种开发模式下安装本地包的方式从这一版开始底层实现换了对很多使用 setuptools 开发包的项目来说这个变化直接影响安装行为。第二pip 21.3 开始强化了对 Python 版本的要求不再支持 Python 2.7 等老旧版本。如果你还在维护 Python 2 的项目那你的 pip 版本基本上就只能锁死在 20.x 或更早21.3.1 装上去也跑不起来。第三从 21.3 到后面的 22.x、23.x、24.xpip 的依赖解析器逐步成熟但很多老项目的requirements.txt里没有精确锁定传递依赖的版本直接升到新版 pip 后会出现解析失败的情况。所以不少团队干脆把 pip 锁在老版本用起来反而稳定。2.3 什么时候才需要手动装 pip-21.3.1.tar.gz给你一个判断清单命中任意一条再考虑手动安装这个源码包你处于完全离线的内网环境机器上连 PyPI 都访问不了但你又需要装一个指定版本的 pip你的操作系统镜像或基础 Docker 镜像里自带的 pip 版本过低而项目要求最低 21.3.1你的环境里ensurepip模块被删了get-pip.py又下载不下来手头只有这个 tar.gz 文件你在做 Python 环境复现实验需要精确到 pip 版本号来保持行为一致。如果没有命中这些情况那我劝你直接在联网环境执行python -m pip install --upgrade pip或者用官方引导脚本curl -sS https://bootstrap.pypa.io/get-pip.py | python这两个方式比手动装 tar.gz 靠谱得多。下面进入正题讲手动安装的具体操作。3. 手动安装 pip-21.3.1.tar.gz 的完整步骤既然要手动装那就把每个细节都说到位包括验证文件、解压安装、配置环境、验证结果一步都别省。3.1 第一步检查当前 Python 环境在安装任何东西之前先确认你手上的 Python 环境是正常的、版本是兼容的。pip 21.3.1 官方要求 Python 版本 3.6所以如果你的 Python 是 3.5 或更老那这个包装不了得先解决 Python 版本问题。打开终端Windows 用 CMD 或 PowerShellmacOS/Linux 用 Terminal执行python --versionWindows 下如果提示python不是内部或外部命令试试py --version如果系统里装了多个 Python 版本python命令指向的可能不是你预期的那一个这时候建议用完整路径或者py -3.8这种形式来指定。我的习惯是在任何安装操作之前都用where pythonWindows或which pythonLinux/macOS确认一下解释器路径避免装完了发现装到了另一个 Python 里那是非常窝火的事。3.2 第二步校验 tar.gz 文件的完整性和安全性tar.gz 本质上是两个操作的组合tar 打包 gzip 压缩。你拿到 pip-21.3.1.tar.gz 后建议先做两件事一是确认压缩包没损坏二是确认内容确实是 pip 的源码。先看压缩包内容tar -tzf pip-21.3.1.tar.gz | head -20正常的话你应该会看到类似这样的输出pip-21.3.1/ pip-21.3.1/PKG-INFO pip-21.3.1/README.rst pip-21.3.1/pyproject.toml pip-21.3.1/setup.cfg pip-21.3.1/src/pip/__init__.py ...注意看有没有pyproject.toml和setup.cfg/setup.py有这些文件才说明这是通过标准打包方式生成的 Python 包安装才有保障。如果解压出来发现只有一堆文档没有代码结构那很可能下载错文件了。安全性方面理论上你应该校验一下 PyPI 官方发布的 SHA256 哈希值但实际操作中很多内网拿到的文件都是通过 U 盘或内部系统拷贝来的校验起来不方便。我的建议是至少确认文件来源是可信的比如从 PyPI 官网或官方镜像站下载而不是从某个论坛的附件链接下载。这是最基本的安全底线。3.3 第三步解压并安装在 Python 环境确认没问题、压缩包也正常之后开始安装。有两种方式效果一样你习惯哪个用哪个。方式一先解压再安装tar -xzvf pip-21.3.1.tar.gz cd pip-21.3.1 python setup.py install方式二直接用 pip 安装本地文件前提是你当前环境里已经有可用的 pippip install ./pip-21.3.1.tar.gz如果当前环境的 pip 版本太老可能会解析不了新格式的 pyproject.toml这时候用方式一更稳妥。等一下这里有个鸡生蛋蛋生鸡的问题如果环境里根本没有 pip怎么用pip install来装 pip没错这就是我最开始说的大多数情况下你不需要手动装 tar.gz因为有一种更简单的方式。但既然你手头已经有这个文件了我可以告诉你一个从零开始的办法先解压然后直接运行源码里的pip入口脚本。tar -xzvf pip-21.3.1.tar.gz cd pip-21.3.1/src python -m pip.__main__ --version如果能看到pip 21.3.1 from ...的输出说明这个源码包整体没毛病。接下来再执行正式安装cd .. python setup.py install装完之后验证一下pip --version python -m pip --version正常输出应该类似pip 21.3.1 from /usr/local/lib/python3.9/site-packages/pip (python 3.9)注意看路径site-packages目录下说明安装的是完整包而不是仅源码模式。3.4 第四步配置环境变量Windows 用户特别注意Windows 下新手最容易栽在环境变量上。pip 装好了但在 CMD 里输入pip提示“不是内部或外部命令”十有八九是 Python 的 Scripts 目录没有加到 PATH 环境变量里。怎么处理打开系统环境变量设置Win R 输入sysdm.cpl或者右键“此电脑” - “属性” - “高级系统设置” - “环境变量”在“系统变量”里找到Path点编辑新增两条Python 安装目录比如C:\Users\你的用户名\AppData\Local\Programs\Python\Python39\Python 安装目录下的Scripts子目录比如C:\Users\你的用户名\AppData\Local\Programs\Python\Python39\Scripts\保存后重新打开 CMD再执行pip --version就能识别了。这一步看起来简单但很多人因为没刷新环境变量或者路径写错卡了很久。我这里多说一句改完环境变量后一定要重开终端窗口不是在新窗口里执行echo %PATH%验证如果你看到的还是旧路径说明新窗口并没有继承最新环境变量需要重启终端甚至注销一次。3.5 安装完成后的环境兼容性检查装好 pip 21.3.1 之后建议顺手做一次“环境体检”确认 pip 能被正常调用、能找到正确的 Python 解释器、能访问包仓库pip --version pip config list pip listpip config list会输出当前的 pip 配置包括是否设置了镜像源、超时时间等。pip list会列出当前环境已安装的所有包如果这个命令能正常跑出来说明 pip 的核心功能是正常的。这一步不是走形式我遇到过好几次装完之后pip --version正常但pip install xxx直接报错的情况原因大多出在配置文件或者网络代理上。提前跑一遍后面少折腾。4. 装完之后新版 pip 的体验和细节pip 21.3.1 安装完成只是第一步真正影响你日常使用的是它的行为变化。这里挑几个实际感受最明显的点讲一讲。4.1 依赖解析器变化可能让你的安装变慢或失败从 pip 20.3 开始pip 默认启用了一个新的依赖解析器resolver比旧版的解析逻辑更严格、更准确。好处是能避免装出一套依赖冲突的环境坏处是解析时间变长而对于一些老项目会因为依赖约束不完整而直接报ResolutionImpossible错误。举个例子我之前在某个项目里需要安装pandas1.3.0但环境里已经有一个包依赖了numpy1.20.0而pandas1.3.0又要求numpy1.20.3新版 resolver 就会报冲突旧版 pip 可能直接忽略这种冲突装上去运行起来再炸。这种变化本身就是设计好的所以遇到解析冲突时不要急着怪 pip仔细看看报错信息里到底是哪几个包冲突了把这几个包的版本约束调整协调即可。如果你实在想临时回到旧版解析器应急用可以不建议长期用可以在安装时加上pip install --use-deprecatedlegacy-resolver 包名但注意pip 21.3.1 中这个选项已经标记为弃用后续版本还会继续移除所以只是应急手段。4.2 配置国内镜像源解决下载慢和超时很多中国开发者用 pip 下载包时最头疼的问题就是速度慢尤其是一些体积大的包比如torch、tensorflow动辄几百 MB。自 pip 21.3 起配置镜像源的方式更成熟了你可以通过配置文件永久生效也可以临时指定。永久配置方式在终端执行pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple这会在当前用户的 pip 配置文件里写入镜像源地址。Linux/macOS 的配置文件路径是~/.config/pip/pip.conf或~/.pip/pip.confWindows 是%APPDATA%\pip\pip.ini。如果不想永久改临时用pip install 包名 -i https://pypi.tuna.tsinghua.edu.cn/simple网上经常看到的清华、阿里、豆瓣、中科大镜像都是 PyPI 的镜像站选一个你觉得快的就行。我自己常年用清华源偶尔也试过阿里源速度差别不大。这里要提醒一句不要在 pip.conf 里配置多个 index-url这东西不支持多镜像轮询写多了只会让最后一个或第一个生效反而产生困惑。网上有个热搜词“是否可以设置多个镜像”答案是可以但要用extra-index-url来追加不能把多个地址写在同一个index-url里。4.3 pip 21.3.1 与 Python 3.10 的兼容性坑pip 21.3.1 发布时Python 3.10 刚发布不久整体兼容性还行但如果你用的是 Python 3.11 或更高版本强烈不建议锁死在 21.3.1因为后面很多底层 API 变化旧版 pip 可能会出现莫名奇妙的问题。我在一台装 Python 3.11 的机器上试过 pip 21.3.1装某些包时偶尔会报ModuleNotFoundError定位了半天最后升级 pip 就好了。所以如果你是因为“图省事”才想用老版本 pip我建议装完后立即升级到新版本pip install --upgrade pip如果你是非要用 21.3.1 不可也请务必将 Python 版本控制在 3.6 ~ 3.10 之间这是目前比较稳妥的搭配区间。5. 实操中遇到的典型问题与排查技巧这一节全是干货我把这些年实际踩过的坑和帮助别人排查过的问题整理成速查表你可以直接收藏。5.1 常见报错速查表报错信息可能原因解决方法pip 不是内部或外部命令环境变量没配好把 Python 的 Scripts 目录加到 PATH重开终端Could not install requirement pip from https://pypi.tuna.tsinghua.edu.cn...镜像源访问异常或 TLS 证书问题先检查网络能否访问镜像再试pip install --trusted-host pypi.tuna.tsinghua.edu.cn pip[notice] A new release of pip is available当前 pip 版本过旧提示有新版本按提示执行pip install --upgrade pipcould not fetch url https://pypi.org/simple/pip/: ...网络无法直连 PyPI配置国内镜像源或走代理pip : 无法将“pip”项识别为 cmdlet、函数、脚本文件...Windows PowerShell 下路径不对用python -m pip代替或修复 PATHpip 不是内部或外部命令,也不是可运行的程序或批处理文件同上CMD 下路径不对同上git clone packet_write_wait: ... broken pipegit 拉取时网络中断或 SSH 连接不稳定检查网络稳定性换 HTTPS 方式拉取不要和 pip 混在一起排查(.venv) PS C:\... pip install提示权限不足虚拟环境目录权限问题以管理员身份运行 PowerShell或重建虚拟环境Win11 使用 pip 已被组织的 Device Guard 策略阻止Windows 安全策略拦截按系统提示放行或解除对 Python 安装目录的阻拦一般需要管理员权限这张表里后面几条尤其是 Windows 系统策略拦截、git clone broken pipe 这些严格说并不完全属于 pip-21.3.1 自身的问题但它们是“pip 使用”热搜里出现频率最高的场景说明很多人把这些坑都归到 pip 上来了。我干脆一并收录方便你排查时有个参照。5.2 排查思路分享报错信息别只看第一行我在帮人看问题的时候发现新手最容易犯的一个毛病就是只看报错的第一行贴到搜索引擎里搜结果搜出来的答案牛头不对马嘴。其实 Python/pip 的报错信息通常会把根因写在最后面比如ERROR: Could not find a version that satisfies the requirement xxx前面的长长内容基本都是堆栈回溯意义不大。所以我的建议是遇到报错先把整个输出复制到文本编辑器里从后往前看。前 30 行可以跳过重点看最后 20 行。如果是依赖冲突报错信息里会明确指出是哪个包和哪个包冲突如果是网络问题会写timed out或connection error如果是编译错误会出现error: command gcc failed之类的信息。根因定位对了解决方式基本也就水到渠成了。5.3 虚拟环境里的 pip 坑很多现代 Python 项目都推荐用虚拟环境venv来隔离依赖。如果你在虚拟环境里手动安装 pip 老版本注意一个问题虚拟环境中的 pip 和全局 Python 的 pip 是两套东西别装错了。创建虚拟环境后里面默认会带一个 pip版本跟随你创建 venv 时用的 Python 版本。如果你想在虚拟环境里降级 pip可以这样python -m venv myenv # Windows myenv\Scripts\activate # Linux/macOS source myenv/bin/activate python -m pip install pip21.3.1注意在虚拟环境里建议始终用python -m pip而不是裸的pip因为虚拟环境激活后pip指向的是环境里的 Scripts 目录正常情况下没问题但如果你手动改过 PATH或者激活脚本执行不完整裸pip可能会跑到全局环境里。用python -m pip就永远指向当前解释器对应的 pip逻辑上更安全。5.4 离线安装场景的完整通路离线环境是很多人手动装 tar.gz 的最常见场景。这里我分享一个完整的离线安装流程适合纯内网机器。先在联网机器上下载必要的文件# 下载 pip 源码包 curl -O https://files.pythonhosted.org/packages/.../pip-21.3.1.tar.gz # 或者用 pip 下载 pip download pip21.3.1 --no-deps -d ./offline_packages然后把pip-21.3.1.tar.gz拷贝到内网机器上执行tar -xzvf pip-21.3.1.tar.gz cd pip-21.3.1 python setup.py install装完验证python -m pip --version如果你还需要离线装其他包可以在联网机器上先批量下载pip download -r requirements.txt -d ./offline_packages -i https://pypi.tuna.tsinghua.edu.cn/simple然后把整个offline_packages目录拷到内网再执行pip install --no-index --find-links./offline_packages -r requirements.txt--no-index表示不访问 PyPI--find-links表示从这个本地目录找包。这套流程我用了很多年稳得很。整套离线通路里pip-21.3.1.tar.gz只是第一步先把 pip 装起来后续装其他包就顺畅了。6. 关于镜像源和代理的进阶配置镜像源和代理属于“能让你安装更顺畅”的进阶内容。既然最近热搜里频繁出现“pip 清华源”“pip 换源”“pip 镜像”我就把这些配置再展开讲讲。6.1 换源的实际操作与优先级pip 的配置优先级是命令行参数 环境变量 用户配置文件 全局配置文件。所以如果你在命令行里加了-i参数它一定覆盖配置文件里的 index-url。配置文件的方式前面已经说了这里再补一个更完整的多源配置写法。如果你希望“先试清华源再试阿里源”有一个思路是设置 extra-index-url[global] index-url https://pypi.tuna.tsinghua.edu.cn/simple extra-index-url https://mirrors.aliyun.com/pypi/simple/但注意extra-index-url 并不是“备胎”机制它只是把多个源都纳入搜索范围pip 会从所有源里找包哪个有就用哪个。这种配置会稍微增加解析时间而且如果不同源的包版本不一致偶尔会出现“从源 A 解析到旧版、从源 B 解析到新版”的情况让人摸不着头脑。所以我个人建议保持单一镜像源稳定优先。常用镜像站地址我顺手整理成表格镜像站地址清华大学 TUNAhttps://pypi.tuna.tsinghua.edu.cn/simple阿里云https://mirrors.aliyun.com/pypi/simple/豆瓣https://pypi.douban.com/simple中科大 USTChttps://pypi.mirrors.ustc.edu.cn/simple/腾讯云https://mirrors.cloud.tencent.com/pypi/simple豆瓣源这几年更新频率稍微慢一点部分新包可能同步不及时遇到“找不到包”时可以换其他源试试。6.2 走代理安装包的配置在公司网络或者部分网络环境下直接访问 PyPI 大概率超时这时候需要给 pip 配置代理。pip 是支持环境变量代理的也可以写在配置文件里。临时使用在命令行里先设置环境变量再执行 pip# Linux/macOS export http_proxyhttp://proxy.example.com:8080 export https_proxyhttp://proxy.example.com:8080 pip install 包名 # Windows PowerShell $env:http_proxyhttp://proxy.example.com:8080 $env:https_proxyhttp://proxy.example.com:8080 pip install 包名永久配置可以在 pip.conf / pip.ini 里加[global] proxy http://proxy.example.com:8080实测下来代理配置后安装速度通常能提升不少但前提是代理本身稳定。如果代理不稳定反而会报更奇怪的错误这时候可以先unset http_proxy再试。6.3 内网私有镜像源搭建的思路如果你的团队很大每次都在联网机器上下包再拷贝效率太低。这时候可以考虑搭一个内网的 PyPI 镜像源。常用的方案是 devpi它是开源的 PyPI 代理和私有包托管服务。devpi 的基本思路是在内网一台机器上装 devpi把这个地址作为 pip 的 index-url它内部会从 PyPI 拉包并缓存。这样大家执行pip install就是内网速度而且包会上传到缓存里下次别人下载就直接命中缓存不再走外网。搭建步骤如下pip install devpi-server devpi-client devpi-init devpi-server --start --port 3141然后在客户端机器上配置pip config set global.index-url http://内网IP:3141/root/pypi/simple/这样整个团队的基础包管理就正规起来了。这个思路适合团队规模大一点的场景如果只是个人或小团队离线拷贝反而更省事。6.4 修改 pip search 的仓库这里插一个热搜词“修改 pip search 的仓库”。pip search命令在 pip 21.3.1 里其实已经废弃了因为 PyPI 的 XML-RPC 搜索接口被官方关闭导致这个命令长期不可用后来官方干脆从命令行里移除了。所以如果你在网上搜到这种教程看年代就知道大概是什么时候的东西了。如果你确实需要搜索包有两个替代方案一是直接到 PyPI 网站上搜索这最简单二是用pip index versions 包名来查看某个包的可用版本列表pip index versions requests这个命令在 pip 21.3.1 里是可用的输出会列出所有可选的版本号。但它不会像pip search那样做关键词模糊搜索而是精确查询某个包的信息。还有一个第三方替代品叫pip-search需要单独安装pip install pip-search它通过调用 PyPI 的 JSON API 来实现搜索但不建议在离线环境折腾这个意义不大。7. 玩转 pip日常高频命令与避坑习惯现在 pip 已经装好镜像源也配置了接下来就是日常使用。高频命令不难但有几个细节和处理习惯能帮你省下不少时间。7.1 日常工作流里最常用的 pip 命令安装、卸载、查看、导出依赖这几个命令就覆盖了 90% 的日常场景# 安装包 pip install requests # 安装指定版本 pip install requests2.26.0 # 升级包 pip install --upgrade requests # 卸载包 pip uninstall requests # 查看已安装列表 pip list # 查看某个包的详细信息 pip show requests # 导出当前环境的依赖清单 pip freeze requirements.txt # 根据清单安装依赖 pip install -r requirements.txtpip freeze导出的文件里会用精确锁定版本适合构建可复现的环境。但注意pip freeze会把所有间接依赖也导出来如果项目里用了虚拟环境还好如果直接在全局环境里执行会导出一大堆和你项目无关的包反而影响他人复现。更合理的做法是使用pipreqs工具它分析你的项目代码只导出真正被 import 的依赖pip install pipreqs pipreqs ./project --force这个工具在实际项目中用了很多次比pip freeze更能反映项目的真实依赖关系。7.2 使用 requirements.txt 的隐藏注意事项requirements.txt 里不仅可以写包名和版本还可以写一些“高级”语法很多人不知道requests2.26.0 numpy1.21.0,1.23.0 githttps://github.com/xxx/xxx.gitmain#eggxxx -e ./local_package支持直接从 git 仓库安装、支持本地包以可编辑模式安装。这让依赖管理灵活很多但也引入一个坑如果某个包是直接从 git 装的pip freeze导出的格式会带上githttps://...这种链接换到内网离线环境后用这个 requirements.txt 是装不上那个包的。因此离线环境的 requirements.txt 最好单独维护或者使用 pip download 把整个依赖树都下载好再拷进去。7.3 锁定版本别“一刀切”很多团队喜欢把依赖全部锁死requirements.txt里一水的。这在一定阶段内是好事环境可复现、不容易出幺蛾子。但长期锁死也有副作用安全漏洞修复无法及时跟进、Python 版本升级时老依赖跟不上。我的建议是区分两类依赖直接依赖比如flask、django、requests锁死大版本或者精确版本重要发布时可人工评估升级间接依赖比如click、itsdangerous这些被框架拉着装的不锁让 pip 自动解析只在出问题时做临时锁定。这样做既不牺牲环境稳定性又能保留一定的升级灵活性是很多中型项目的通用实践。7.4 一个日常好习惯检查安装位置pip show输出里有一项Location表示该包安装的绝对路径。当你怀疑“我明明装了为什么 import 不到”时先看pip show的 Location 和你代码运行时的sys.path是否匹配。我遇到过好几次因为 virtualenv 没激活、或者 PyCharm 里选了不同的解释器导致安装位置不一致import 报ModuleNotFoundError但pip list里明明有那个包——这种情况十有八九是解释器路径对不上。快速检查python -c import sys; print(sys.executable) pip --version两个输出的路径对应得上的话基本就能排除这个坑了。8. 版本升级与降级pip 的自我管理pip 的一个特殊之处在于它可以管理自己。这个特性让 pip 的版本切换变得很简单但也有一些值得注意的细节。8.1 升级 pip 的正确姿势联网环境下升级 pip 最常用的两种方式python -m pip install --upgrade pip或者python -m pip install pip24.0第一种升到最新版第二种指定版本号。升级完成后如果系统还提示有新版本可能是因为你当前用的pip命令和python -m pip不是同一个环境。用pip --version和python -m pip --version对比一下两个输出应该一致。如果不一致说明 PATH 里的pip和当前默认python不匹配这也是很多“升级了但没升级”的假象源头。8.2 降级 pip 到 21.3.1既然你要装 pip-21.3.1.tar.gz那也有可能是想从新版降级到旧版。在联网环境下直接python -m pip install pip21.3.1新版 pip 会先卸载旧版再装新版整个过程它自己来处理。但有一个小坑如果当前 pip 版本过新比如 24.x降级时可能会出现Cannot uninstall pip的提示。这通常是因为操作系统或某些工具对 pip 目录有写保护。解决办法是加--user参数或者用管理员权限python -m pip install --user pip21.3.1装完后验证python -m pip --version8.3 从 tar.gz 手动安装和 pip 在线安装哪个更好这个问题我直接给你结论在线环境永远优先用 pip 在线安装离线环境才考虑 tar.gz 手动安装。原因有三第一pip 在线安装会帮你处理依赖关系而 tar.gz 手动安装通常只装 pip 本身其他依赖需要你自己逐个搞定工作量翻倍。第二pip 在线安装走的是 PyPI 或镜像源的标准流程版本信息、哈希校验都完整手动装 tar.gz 反而要自己操心文件安全性和完整性。第三pip 在线安装可以自动卸载旧版本手动装 tar.gz 则可能出现“源码解压的内容和旧版残留混在一起”的情况导致一些奇怪的报错。所以除非你明确知道自己为什么不用在线安装否则优先在线。9. 我的实操体会与最后的建议写到这里关于 pip-21.3.1.tar.gz 的安装、配置、使用和排查基本都覆盖到了。最后分享几条我从实际工作中总结出来的经验。第一条pip 版本不是越新越好也不是越旧越稳而是要根据你的项目环境和运行场景来选。如果你只是在做简单的脚本开发、装几个常用库用官方最新版就行如果你在维护老项目requirements.txt里锁定了大量旧版本依赖那 pip 版本保守一点反而更省心。pip 21.3.1 这个版本恰好是一个“不出彩但稳定”的过渡版本如果你已经在用也不必急着升。第二条镜像源要在项目开始时配好而不是等超时了才想起换源。我每次在新机器上配置 Python 环境第一件事就是设置清华源、升级 pip然后才创建虚拟环境、装依赖。这套顺序能避免很多无谓的网络等待。第三条遇到 pip 报错先深呼吸把完整报错信息复制下来从最后往前读。大部分问题都是环境问题、网络问题、依赖冲突问题这三类定位到根因后解决起来非常快。等你熟练之后就会发现 pip 其实没有那么多玄学绝大多数坑都是可以被理性排查解决的。最后再分享一个实操小技巧如果你在离线环境安装完 pip-21.3.1.tar.gz 之后建议立刻用python -m pip config set global.index-url配置一个公司内网的镜像源或者明确知道当前的 index-url 是无效的避免后续安装包时再去纠结网络问题。如果你需要经常给别人搭环境还可以把下载好的 pip-21.3.1.tar.gz 连同常用的几个包一起打成一个离线工具包走到哪里都能快速部署这才是真正省力气的做法。本文还有配套的精品资源点击获取
pip-21.3.1.tar.gz手动安装详解：从环境检查到镜像源配置
简介面向 Python 开发者的 pip 21.3.1 官方源码包适合需要深入理解包管理器实现机制、进行离线安装或二次定制的读者。该版本包含 install、uninstall、show、list 等常用命令的完整实现也覆盖依赖约束、虚拟环境、镜像源与安全选项等核心逻辑可作为学习 Python 打包分发原理的参考材料。包体共 538 个文件以 402 个 Python 源码文件为主另有 67 个 RST 文档、17 个 Markdown 说明、15 个许可证文件及若干 cfg、toml、pem 等配置类文件整体结构清晰便于按模块查阅压缩包大小约 1.65MB轻量而完整。已有 1593 人学习使用。通过分析源码可掌握 pip 的安装升级流程、版本解析与依赖处理思路也可直接提取其中工具脚本用于自定义包管理场景对提升 Python 工程化能力有直接帮助。1. 拿到 pip-21.3.1.tar.gz先别急着装如果你搜到这个文件名大概率是遇到了下面三种情况之一要么是手动从 PyPI 官网把 pip 源码包下载下来了要么是在内网离线环境里需要自己装 pip要么就是跟着某篇教程操作结果教程给的链接直接指向了这个 tar.gz 文件。不管是哪种先把结论放在前面在绝大多数情况下你根本不需要手动安装 pip-21.3.1.tar.gz直接用官方推荐的引导命令python -m ensurepip或者get-pip.py就能搞定而且更省事、更不容易踩坑。那为什么网上还有这么多人在找这个包因为 pip 从 21.3 开始变化很大很多老教程、老脚本里写死了版本号导致后来的人照抄时被带偏。再加上 pip 21.3.1 恰好处于一个“旧版能用、新版更好”的过渡期很多人为了兼容旧项目、旧依赖锁文件就非得用这个版本不可。我自己也有一台内网机器常年不连外网系统自带的 Python 版本又老pip 装不上、装上了又用不了的情况见过太多次了。所以这篇文章就围绕 pip-21.3.1.tar.gz 这个文件把“什么时候需要它、怎么正确装它、装上之后怎么用、遇到问题怎么排查”整个链路讲透。适合谁看三种人一是刚入门 Python、被各种报错折磨的新手搞不清 pip 到底怎么回事二是需要在离线或内网环境部署 Python 环境的运维和开发三是项目依赖锁定在旧版本 pip、被迫手动装包的老项目维护者。不管你是哪种这篇文章都会给你一套可以直接照做的方案。2. 先搞清楚pip 到底是个什么东西在动手装之前我建议你先花两分钟把 pip 的本质搞清楚不然以后遇到各种奇怪问题还是会一脸懵。2.1 pip 是什么它和 Python 是什么关系pip 是 Python 官方的包管理工具全称叫 Pip Installs Packages作用是帮你从 PyPIPython Package IndexPython 官方软件包仓库下载、安装、卸载、管理第三方库。你可以把它理解成手机上的应用商店Python 是手机系统pip 是应用商店各种第三方库就是 App。你想装一个 App不用自己去网上找安装包直接在应用商店里搜索安装就行pip 干的就是这件事。pip 本身也是用 Python 写的所以它也是一个 Python 包也可以被 pip 自己管理。这就出现了一个有点绕但很关键的点pip 可以升级 pip 自己。当你执行pip install --upgrade pip时本质上是把当前环境里的 pip 包替换成新版本。由于 pip 的版本迭代非常频繁PyPI 上每几个月就会发布一个或多个新版本所以网上的教程、Docker 镜像、CI 脚本里经常会看到“安装指定版本 pip”这类需求。2.2 pip 21.3.1 这个版本特殊在哪pip 21.3.1 发布于 2021 年 11 月属于 pip 21.3 系列的一个 bugfix 版本。这个版本之所以在网络上还有不小的存在感是因为它处在几个关键变化的节点上第一pip 21.3 是默认启用 PEP 660可编辑安装的新机制的首个大版本。简单说pip install -e .这种开发模式下安装本地包的方式从这一版开始底层实现换了对很多使用 setuptools 开发包的项目来说这个变化直接影响安装行为。第二pip 21.3 开始强化了对 Python 版本的要求不再支持 Python 2.7 等老旧版本。如果你还在维护 Python 2 的项目那你的 pip 版本基本上就只能锁死在 20.x 或更早21.3.1 装上去也跑不起来。第三从 21.3 到后面的 22.x、23.x、24.xpip 的依赖解析器逐步成熟但很多老项目的requirements.txt里没有精确锁定传递依赖的版本直接升到新版 pip 后会出现解析失败的情况。所以不少团队干脆把 pip 锁在老版本用起来反而稳定。2.3 什么时候才需要手动装 pip-21.3.1.tar.gz给你一个判断清单命中任意一条再考虑手动安装这个源码包你处于完全离线的内网环境机器上连 PyPI 都访问不了但你又需要装一个指定版本的 pip你的操作系统镜像或基础 Docker 镜像里自带的 pip 版本过低而项目要求最低 21.3.1你的环境里ensurepip模块被删了get-pip.py又下载不下来手头只有这个 tar.gz 文件你在做 Python 环境复现实验需要精确到 pip 版本号来保持行为一致。如果没有命中这些情况那我劝你直接在联网环境执行python -m pip install --upgrade pip或者用官方引导脚本curl -sS https://bootstrap.pypa.io/get-pip.py | python这两个方式比手动装 tar.gz 靠谱得多。下面进入正题讲手动安装的具体操作。3. 手动安装 pip-21.3.1.tar.gz 的完整步骤既然要手动装那就把每个细节都说到位包括验证文件、解压安装、配置环境、验证结果一步都别省。3.1 第一步检查当前 Python 环境在安装任何东西之前先确认你手上的 Python 环境是正常的、版本是兼容的。pip 21.3.1 官方要求 Python 版本 3.6所以如果你的 Python 是 3.5 或更老那这个包装不了得先解决 Python 版本问题。打开终端Windows 用 CMD 或 PowerShellmacOS/Linux 用 Terminal执行python --versionWindows 下如果提示python不是内部或外部命令试试py --version如果系统里装了多个 Python 版本python命令指向的可能不是你预期的那一个这时候建议用完整路径或者py -3.8这种形式来指定。我的习惯是在任何安装操作之前都用where pythonWindows或which pythonLinux/macOS确认一下解释器路径避免装完了发现装到了另一个 Python 里那是非常窝火的事。3.2 第二步校验 tar.gz 文件的完整性和安全性tar.gz 本质上是两个操作的组合tar 打包 gzip 压缩。你拿到 pip-21.3.1.tar.gz 后建议先做两件事一是确认压缩包没损坏二是确认内容确实是 pip 的源码。先看压缩包内容tar -tzf pip-21.3.1.tar.gz | head -20正常的话你应该会看到类似这样的输出pip-21.3.1/ pip-21.3.1/PKG-INFO pip-21.3.1/README.rst pip-21.3.1/pyproject.toml pip-21.3.1/setup.cfg pip-21.3.1/src/pip/__init__.py ...注意看有没有pyproject.toml和setup.cfg/setup.py有这些文件才说明这是通过标准打包方式生成的 Python 包安装才有保障。如果解压出来发现只有一堆文档没有代码结构那很可能下载错文件了。安全性方面理论上你应该校验一下 PyPI 官方发布的 SHA256 哈希值但实际操作中很多内网拿到的文件都是通过 U 盘或内部系统拷贝来的校验起来不方便。我的建议是至少确认文件来源是可信的比如从 PyPI 官网或官方镜像站下载而不是从某个论坛的附件链接下载。这是最基本的安全底线。3.3 第三步解压并安装在 Python 环境确认没问题、压缩包也正常之后开始安装。有两种方式效果一样你习惯哪个用哪个。方式一先解压再安装tar -xzvf pip-21.3.1.tar.gz cd pip-21.3.1 python setup.py install方式二直接用 pip 安装本地文件前提是你当前环境里已经有可用的 pippip install ./pip-21.3.1.tar.gz如果当前环境的 pip 版本太老可能会解析不了新格式的 pyproject.toml这时候用方式一更稳妥。等一下这里有个鸡生蛋蛋生鸡的问题如果环境里根本没有 pip怎么用pip install来装 pip没错这就是我最开始说的大多数情况下你不需要手动装 tar.gz因为有一种更简单的方式。但既然你手头已经有这个文件了我可以告诉你一个从零开始的办法先解压然后直接运行源码里的pip入口脚本。tar -xzvf pip-21.3.1.tar.gz cd pip-21.3.1/src python -m pip.__main__ --version如果能看到pip 21.3.1 from ...的输出说明这个源码包整体没毛病。接下来再执行正式安装cd .. python setup.py install装完之后验证一下pip --version python -m pip --version正常输出应该类似pip 21.3.1 from /usr/local/lib/python3.9/site-packages/pip (python 3.9)注意看路径site-packages目录下说明安装的是完整包而不是仅源码模式。3.4 第四步配置环境变量Windows 用户特别注意Windows 下新手最容易栽在环境变量上。pip 装好了但在 CMD 里输入pip提示“不是内部或外部命令”十有八九是 Python 的 Scripts 目录没有加到 PATH 环境变量里。怎么处理打开系统环境变量设置Win R 输入sysdm.cpl或者右键“此电脑” - “属性” - “高级系统设置” - “环境变量”在“系统变量”里找到Path点编辑新增两条Python 安装目录比如C:\Users\你的用户名\AppData\Local\Programs\Python\Python39\Python 安装目录下的Scripts子目录比如C:\Users\你的用户名\AppData\Local\Programs\Python\Python39\Scripts\保存后重新打开 CMD再执行pip --version就能识别了。这一步看起来简单但很多人因为没刷新环境变量或者路径写错卡了很久。我这里多说一句改完环境变量后一定要重开终端窗口不是在新窗口里执行echo %PATH%验证如果你看到的还是旧路径说明新窗口并没有继承最新环境变量需要重启终端甚至注销一次。3.5 安装完成后的环境兼容性检查装好 pip 21.3.1 之后建议顺手做一次“环境体检”确认 pip 能被正常调用、能找到正确的 Python 解释器、能访问包仓库pip --version pip config list pip listpip config list会输出当前的 pip 配置包括是否设置了镜像源、超时时间等。pip list会列出当前环境已安装的所有包如果这个命令能正常跑出来说明 pip 的核心功能是正常的。这一步不是走形式我遇到过好几次装完之后pip --version正常但pip install xxx直接报错的情况原因大多出在配置文件或者网络代理上。提前跑一遍后面少折腾。4. 装完之后新版 pip 的体验和细节pip 21.3.1 安装完成只是第一步真正影响你日常使用的是它的行为变化。这里挑几个实际感受最明显的点讲一讲。4.1 依赖解析器变化可能让你的安装变慢或失败从 pip 20.3 开始pip 默认启用了一个新的依赖解析器resolver比旧版的解析逻辑更严格、更准确。好处是能避免装出一套依赖冲突的环境坏处是解析时间变长而对于一些老项目会因为依赖约束不完整而直接报ResolutionImpossible错误。举个例子我之前在某个项目里需要安装pandas1.3.0但环境里已经有一个包依赖了numpy1.20.0而pandas1.3.0又要求numpy1.20.3新版 resolver 就会报冲突旧版 pip 可能直接忽略这种冲突装上去运行起来再炸。这种变化本身就是设计好的所以遇到解析冲突时不要急着怪 pip仔细看看报错信息里到底是哪几个包冲突了把这几个包的版本约束调整协调即可。如果你实在想临时回到旧版解析器应急用可以不建议长期用可以在安装时加上pip install --use-deprecatedlegacy-resolver 包名但注意pip 21.3.1 中这个选项已经标记为弃用后续版本还会继续移除所以只是应急手段。4.2 配置国内镜像源解决下载慢和超时很多中国开发者用 pip 下载包时最头疼的问题就是速度慢尤其是一些体积大的包比如torch、tensorflow动辄几百 MB。自 pip 21.3 起配置镜像源的方式更成熟了你可以通过配置文件永久生效也可以临时指定。永久配置方式在终端执行pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple这会在当前用户的 pip 配置文件里写入镜像源地址。Linux/macOS 的配置文件路径是~/.config/pip/pip.conf或~/.pip/pip.confWindows 是%APPDATA%\pip\pip.ini。如果不想永久改临时用pip install 包名 -i https://pypi.tuna.tsinghua.edu.cn/simple网上经常看到的清华、阿里、豆瓣、中科大镜像都是 PyPI 的镜像站选一个你觉得快的就行。我自己常年用清华源偶尔也试过阿里源速度差别不大。这里要提醒一句不要在 pip.conf 里配置多个 index-url这东西不支持多镜像轮询写多了只会让最后一个或第一个生效反而产生困惑。网上有个热搜词“是否可以设置多个镜像”答案是可以但要用extra-index-url来追加不能把多个地址写在同一个index-url里。4.3 pip 21.3.1 与 Python 3.10 的兼容性坑pip 21.3.1 发布时Python 3.10 刚发布不久整体兼容性还行但如果你用的是 Python 3.11 或更高版本强烈不建议锁死在 21.3.1因为后面很多底层 API 变化旧版 pip 可能会出现莫名奇妙的问题。我在一台装 Python 3.11 的机器上试过 pip 21.3.1装某些包时偶尔会报ModuleNotFoundError定位了半天最后升级 pip 就好了。所以如果你是因为“图省事”才想用老版本 pip我建议装完后立即升级到新版本pip install --upgrade pip如果你是非要用 21.3.1 不可也请务必将 Python 版本控制在 3.6 ~ 3.10 之间这是目前比较稳妥的搭配区间。5. 实操中遇到的典型问题与排查技巧这一节全是干货我把这些年实际踩过的坑和帮助别人排查过的问题整理成速查表你可以直接收藏。5.1 常见报错速查表报错信息可能原因解决方法pip 不是内部或外部命令环境变量没配好把 Python 的 Scripts 目录加到 PATH重开终端Could not install requirement pip from https://pypi.tuna.tsinghua.edu.cn...镜像源访问异常或 TLS 证书问题先检查网络能否访问镜像再试pip install --trusted-host pypi.tuna.tsinghua.edu.cn pip[notice] A new release of pip is available当前 pip 版本过旧提示有新版本按提示执行pip install --upgrade pipcould not fetch url https://pypi.org/simple/pip/: ...网络无法直连 PyPI配置国内镜像源或走代理pip : 无法将“pip”项识别为 cmdlet、函数、脚本文件...Windows PowerShell 下路径不对用python -m pip代替或修复 PATHpip 不是内部或外部命令,也不是可运行的程序或批处理文件同上CMD 下路径不对同上git clone packet_write_wait: ... broken pipegit 拉取时网络中断或 SSH 连接不稳定检查网络稳定性换 HTTPS 方式拉取不要和 pip 混在一起排查(.venv) PS C:\... pip install提示权限不足虚拟环境目录权限问题以管理员身份运行 PowerShell或重建虚拟环境Win11 使用 pip 已被组织的 Device Guard 策略阻止Windows 安全策略拦截按系统提示放行或解除对 Python 安装目录的阻拦一般需要管理员权限这张表里后面几条尤其是 Windows 系统策略拦截、git clone broken pipe 这些严格说并不完全属于 pip-21.3.1 自身的问题但它们是“pip 使用”热搜里出现频率最高的场景说明很多人把这些坑都归到 pip 上来了。我干脆一并收录方便你排查时有个参照。5.2 排查思路分享报错信息别只看第一行我在帮人看问题的时候发现新手最容易犯的一个毛病就是只看报错的第一行贴到搜索引擎里搜结果搜出来的答案牛头不对马嘴。其实 Python/pip 的报错信息通常会把根因写在最后面比如ERROR: Could not find a version that satisfies the requirement xxx前面的长长内容基本都是堆栈回溯意义不大。所以我的建议是遇到报错先把整个输出复制到文本编辑器里从后往前看。前 30 行可以跳过重点看最后 20 行。如果是依赖冲突报错信息里会明确指出是哪个包和哪个包冲突如果是网络问题会写timed out或connection error如果是编译错误会出现error: command gcc failed之类的信息。根因定位对了解决方式基本也就水到渠成了。5.3 虚拟环境里的 pip 坑很多现代 Python 项目都推荐用虚拟环境venv来隔离依赖。如果你在虚拟环境里手动安装 pip 老版本注意一个问题虚拟环境中的 pip 和全局 Python 的 pip 是两套东西别装错了。创建虚拟环境后里面默认会带一个 pip版本跟随你创建 venv 时用的 Python 版本。如果你想在虚拟环境里降级 pip可以这样python -m venv myenv # Windows myenv\Scripts\activate # Linux/macOS source myenv/bin/activate python -m pip install pip21.3.1注意在虚拟环境里建议始终用python -m pip而不是裸的pip因为虚拟环境激活后pip指向的是环境里的 Scripts 目录正常情况下没问题但如果你手动改过 PATH或者激活脚本执行不完整裸pip可能会跑到全局环境里。用python -m pip就永远指向当前解释器对应的 pip逻辑上更安全。5.4 离线安装场景的完整通路离线环境是很多人手动装 tar.gz 的最常见场景。这里我分享一个完整的离线安装流程适合纯内网机器。先在联网机器上下载必要的文件# 下载 pip 源码包 curl -O https://files.pythonhosted.org/packages/.../pip-21.3.1.tar.gz # 或者用 pip 下载 pip download pip21.3.1 --no-deps -d ./offline_packages然后把pip-21.3.1.tar.gz拷贝到内网机器上执行tar -xzvf pip-21.3.1.tar.gz cd pip-21.3.1 python setup.py install装完验证python -m pip --version如果你还需要离线装其他包可以在联网机器上先批量下载pip download -r requirements.txt -d ./offline_packages -i https://pypi.tuna.tsinghua.edu.cn/simple然后把整个offline_packages目录拷到内网再执行pip install --no-index --find-links./offline_packages -r requirements.txt--no-index表示不访问 PyPI--find-links表示从这个本地目录找包。这套流程我用了很多年稳得很。整套离线通路里pip-21.3.1.tar.gz只是第一步先把 pip 装起来后续装其他包就顺畅了。6. 关于镜像源和代理的进阶配置镜像源和代理属于“能让你安装更顺畅”的进阶内容。既然最近热搜里频繁出现“pip 清华源”“pip 换源”“pip 镜像”我就把这些配置再展开讲讲。6.1 换源的实际操作与优先级pip 的配置优先级是命令行参数 环境变量 用户配置文件 全局配置文件。所以如果你在命令行里加了-i参数它一定覆盖配置文件里的 index-url。配置文件的方式前面已经说了这里再补一个更完整的多源配置写法。如果你希望“先试清华源再试阿里源”有一个思路是设置 extra-index-url[global] index-url https://pypi.tuna.tsinghua.edu.cn/simple extra-index-url https://mirrors.aliyun.com/pypi/simple/但注意extra-index-url 并不是“备胎”机制它只是把多个源都纳入搜索范围pip 会从所有源里找包哪个有就用哪个。这种配置会稍微增加解析时间而且如果不同源的包版本不一致偶尔会出现“从源 A 解析到旧版、从源 B 解析到新版”的情况让人摸不着头脑。所以我个人建议保持单一镜像源稳定优先。常用镜像站地址我顺手整理成表格镜像站地址清华大学 TUNAhttps://pypi.tuna.tsinghua.edu.cn/simple阿里云https://mirrors.aliyun.com/pypi/simple/豆瓣https://pypi.douban.com/simple中科大 USTChttps://pypi.mirrors.ustc.edu.cn/simple/腾讯云https://mirrors.cloud.tencent.com/pypi/simple豆瓣源这几年更新频率稍微慢一点部分新包可能同步不及时遇到“找不到包”时可以换其他源试试。6.2 走代理安装包的配置在公司网络或者部分网络环境下直接访问 PyPI 大概率超时这时候需要给 pip 配置代理。pip 是支持环境变量代理的也可以写在配置文件里。临时使用在命令行里先设置环境变量再执行 pip# Linux/macOS export http_proxyhttp://proxy.example.com:8080 export https_proxyhttp://proxy.example.com:8080 pip install 包名 # Windows PowerShell $env:http_proxyhttp://proxy.example.com:8080 $env:https_proxyhttp://proxy.example.com:8080 pip install 包名永久配置可以在 pip.conf / pip.ini 里加[global] proxy http://proxy.example.com:8080实测下来代理配置后安装速度通常能提升不少但前提是代理本身稳定。如果代理不稳定反而会报更奇怪的错误这时候可以先unset http_proxy再试。6.3 内网私有镜像源搭建的思路如果你的团队很大每次都在联网机器上下包再拷贝效率太低。这时候可以考虑搭一个内网的 PyPI 镜像源。常用的方案是 devpi它是开源的 PyPI 代理和私有包托管服务。devpi 的基本思路是在内网一台机器上装 devpi把这个地址作为 pip 的 index-url它内部会从 PyPI 拉包并缓存。这样大家执行pip install就是内网速度而且包会上传到缓存里下次别人下载就直接命中缓存不再走外网。搭建步骤如下pip install devpi-server devpi-client devpi-init devpi-server --start --port 3141然后在客户端机器上配置pip config set global.index-url http://内网IP:3141/root/pypi/simple/这样整个团队的基础包管理就正规起来了。这个思路适合团队规模大一点的场景如果只是个人或小团队离线拷贝反而更省事。6.4 修改 pip search 的仓库这里插一个热搜词“修改 pip search 的仓库”。pip search命令在 pip 21.3.1 里其实已经废弃了因为 PyPI 的 XML-RPC 搜索接口被官方关闭导致这个命令长期不可用后来官方干脆从命令行里移除了。所以如果你在网上搜到这种教程看年代就知道大概是什么时候的东西了。如果你确实需要搜索包有两个替代方案一是直接到 PyPI 网站上搜索这最简单二是用pip index versions 包名来查看某个包的可用版本列表pip index versions requests这个命令在 pip 21.3.1 里是可用的输出会列出所有可选的版本号。但它不会像pip search那样做关键词模糊搜索而是精确查询某个包的信息。还有一个第三方替代品叫pip-search需要单独安装pip install pip-search它通过调用 PyPI 的 JSON API 来实现搜索但不建议在离线环境折腾这个意义不大。7. 玩转 pip日常高频命令与避坑习惯现在 pip 已经装好镜像源也配置了接下来就是日常使用。高频命令不难但有几个细节和处理习惯能帮你省下不少时间。7.1 日常工作流里最常用的 pip 命令安装、卸载、查看、导出依赖这几个命令就覆盖了 90% 的日常场景# 安装包 pip install requests # 安装指定版本 pip install requests2.26.0 # 升级包 pip install --upgrade requests # 卸载包 pip uninstall requests # 查看已安装列表 pip list # 查看某个包的详细信息 pip show requests # 导出当前环境的依赖清单 pip freeze requirements.txt # 根据清单安装依赖 pip install -r requirements.txtpip freeze导出的文件里会用精确锁定版本适合构建可复现的环境。但注意pip freeze会把所有间接依赖也导出来如果项目里用了虚拟环境还好如果直接在全局环境里执行会导出一大堆和你项目无关的包反而影响他人复现。更合理的做法是使用pipreqs工具它分析你的项目代码只导出真正被 import 的依赖pip install pipreqs pipreqs ./project --force这个工具在实际项目中用了很多次比pip freeze更能反映项目的真实依赖关系。7.2 使用 requirements.txt 的隐藏注意事项requirements.txt 里不仅可以写包名和版本还可以写一些“高级”语法很多人不知道requests2.26.0 numpy1.21.0,1.23.0 githttps://github.com/xxx/xxx.gitmain#eggxxx -e ./local_package支持直接从 git 仓库安装、支持本地包以可编辑模式安装。这让依赖管理灵活很多但也引入一个坑如果某个包是直接从 git 装的pip freeze导出的格式会带上githttps://...这种链接换到内网离线环境后用这个 requirements.txt 是装不上那个包的。因此离线环境的 requirements.txt 最好单独维护或者使用 pip download 把整个依赖树都下载好再拷进去。7.3 锁定版本别“一刀切”很多团队喜欢把依赖全部锁死requirements.txt里一水的。这在一定阶段内是好事环境可复现、不容易出幺蛾子。但长期锁死也有副作用安全漏洞修复无法及时跟进、Python 版本升级时老依赖跟不上。我的建议是区分两类依赖直接依赖比如flask、django、requests锁死大版本或者精确版本重要发布时可人工评估升级间接依赖比如click、itsdangerous这些被框架拉着装的不锁让 pip 自动解析只在出问题时做临时锁定。这样做既不牺牲环境稳定性又能保留一定的升级灵活性是很多中型项目的通用实践。7.4 一个日常好习惯检查安装位置pip show输出里有一项Location表示该包安装的绝对路径。当你怀疑“我明明装了为什么 import 不到”时先看pip show的 Location 和你代码运行时的sys.path是否匹配。我遇到过好几次因为 virtualenv 没激活、或者 PyCharm 里选了不同的解释器导致安装位置不一致import 报ModuleNotFoundError但pip list里明明有那个包——这种情况十有八九是解释器路径对不上。快速检查python -c import sys; print(sys.executable) pip --version两个输出的路径对应得上的话基本就能排除这个坑了。8. 版本升级与降级pip 的自我管理pip 的一个特殊之处在于它可以管理自己。这个特性让 pip 的版本切换变得很简单但也有一些值得注意的细节。8.1 升级 pip 的正确姿势联网环境下升级 pip 最常用的两种方式python -m pip install --upgrade pip或者python -m pip install pip24.0第一种升到最新版第二种指定版本号。升级完成后如果系统还提示有新版本可能是因为你当前用的pip命令和python -m pip不是同一个环境。用pip --version和python -m pip --version对比一下两个输出应该一致。如果不一致说明 PATH 里的pip和当前默认python不匹配这也是很多“升级了但没升级”的假象源头。8.2 降级 pip 到 21.3.1既然你要装 pip-21.3.1.tar.gz那也有可能是想从新版降级到旧版。在联网环境下直接python -m pip install pip21.3.1新版 pip 会先卸载旧版再装新版整个过程它自己来处理。但有一个小坑如果当前 pip 版本过新比如 24.x降级时可能会出现Cannot uninstall pip的提示。这通常是因为操作系统或某些工具对 pip 目录有写保护。解决办法是加--user参数或者用管理员权限python -m pip install --user pip21.3.1装完后验证python -m pip --version8.3 从 tar.gz 手动安装和 pip 在线安装哪个更好这个问题我直接给你结论在线环境永远优先用 pip 在线安装离线环境才考虑 tar.gz 手动安装。原因有三第一pip 在线安装会帮你处理依赖关系而 tar.gz 手动安装通常只装 pip 本身其他依赖需要你自己逐个搞定工作量翻倍。第二pip 在线安装走的是 PyPI 或镜像源的标准流程版本信息、哈希校验都完整手动装 tar.gz 反而要自己操心文件安全性和完整性。第三pip 在线安装可以自动卸载旧版本手动装 tar.gz 则可能出现“源码解压的内容和旧版残留混在一起”的情况导致一些奇怪的报错。所以除非你明确知道自己为什么不用在线安装否则优先在线。9. 我的实操体会与最后的建议写到这里关于 pip-21.3.1.tar.gz 的安装、配置、使用和排查基本都覆盖到了。最后分享几条我从实际工作中总结出来的经验。第一条pip 版本不是越新越好也不是越旧越稳而是要根据你的项目环境和运行场景来选。如果你只是在做简单的脚本开发、装几个常用库用官方最新版就行如果你在维护老项目requirements.txt里锁定了大量旧版本依赖那 pip 版本保守一点反而更省心。pip 21.3.1 这个版本恰好是一个“不出彩但稳定”的过渡版本如果你已经在用也不必急着升。第二条镜像源要在项目开始时配好而不是等超时了才想起换源。我每次在新机器上配置 Python 环境第一件事就是设置清华源、升级 pip然后才创建虚拟环境、装依赖。这套顺序能避免很多无谓的网络等待。第三条遇到 pip 报错先深呼吸把完整报错信息复制下来从最后往前读。大部分问题都是环境问题、网络问题、依赖冲突问题这三类定位到根因后解决起来非常快。等你熟练之后就会发现 pip 其实没有那么多玄学绝大多数坑都是可以被理性排查解决的。最后再分享一个实操小技巧如果你在离线环境安装完 pip-21.3.1.tar.gz 之后建议立刻用python -m pip config set global.index-url配置一个公司内网的镜像源或者明确知道当前的 index-url 是无效的避免后续安装包时再去纠结网络问题。如果你需要经常给别人搭环境还可以把下载好的 pip-21.3.1.tar.gz 连同常用的几个包一起打成一个离线工具包走到哪里都能快速部署这才是真正省力气的做法。本文还有配套的精品资源点击获取
