运行 pip install 后,下载长时间没有进度,可能是当前网络连接 PyPI 不顺畅。可以试试 pip 阿里云镜像:把 pip 查询和下载软件包时使用的索引地址切换到阿里云镜像站。临时安装只需在命令中指定地址;如果经常遇到下载慢,也可以写入 pip 配置,让它默认使用这个镜像。
什么是 pip 阿里云镜像
pip 是 Python 常用的包管理工具,PyPI 是 Python 软件包的主要索引站点。执行 pip install requests 时,pip 会查询索引并下载所需的软件包。使用镜像,就是把查询和下载所用的索引地址换成镜像站。
阿里云 PyPI 镜像的常用地址是:
https://mirrors.aliyun.com/pypi/simple/
切换镜像不会改变 pip install 的基本用法,也不会额外安装一个包管理器。需要留意的是,镜像站与 PyPI 之间可能存在同步时间差。刚发布或刚更新的软件包,暂时无法在镜像上查到时,不一定是包名写错了。
临时使用:只对当前安装生效
如果只是某一次安装比较慢,不想调整电脑的默认设置,可以在命令后加上 -i 参数:
python -m pip install requests -i https://mirrors.aliyun.com/pypi/simple/
这里用 python -m pip 调用 pip,可以减少电脑安装了多个 Python 版本时,用错 pip 的情况。比如项目使用的是某个虚拟环境中的 Python,直接输入 pip install 有可能调用到另一个环境的 pip;通过对应的 Python 执行 -m pip,更容易确认安装目标。
把命令里的 requests 换成需要安装的软件包即可,例如:
python -m pip install numpy -i https://mirrors.aliyun.com/pypi/simple/
临时指定镜像只影响这条命令,不会改动后续安装的默认来源。临时排查服务器下载慢、测试镜像是否可用,或者某个项目需要使用不同索引时,这种方式更容易控制。
长期使用:设置 pip 默认镜像
如果平时经常通过 pip 安装软件包,可以将镜像地址写入配置。完成后,执行普通安装命令时会默认使用该索引,不必每次都手动输入镜像地址。
通过命令设置
较新的 pip 通常支持用配置命令设置默认索引:
python -m pip config set global.index-url https://mirrors.aliyun.com/pypi/simple/
设置后运行以下命令,检查配置是否已写入:
python -m pip config list
如果输出中能看到 global.index-url 和对应的镜像地址,说明配置已生效。之后安装软件包时可以直接运行:
python -m pip install flask
如果提示不支持 pip config,可以先检查 pip 版本;也可以手动编辑配置文件。
手动编辑配置文件
在 pip 配置文件中加入下面两行即可:
[global]
index-url = https://mirrors.aliyun.com/pypi/simple/
- Windows:常见位置是
%APPDATA%\pip\pip.ini,例如用户目录下的AppData\Roaming\pip\pip.ini。如果文件或目录不存在,需要先创建。 - macOS、Linux:常见位置是
~/.config/pip/pip.conf;一些较旧的环境也会读取~/.pip/pip.conf。
配置路径会随操作系统和 pip 版本有所不同。找不到配置文件时,可以运行 python -m pip config debug,查看 pip 正在检查哪些位置。编辑后再用 python -m pip config list 核对,比只凭文件位置判断是否生效更稳妥。
安装卡住时,按这几步排查
例如,在 Windows 上开发 Flask 项目,运行 pip install flask 后一直停在下载阶段。可以先用临时参数测试:
python -m pip install flask -i https://mirrors.aliyun.com/pypi/simple/
如果下载恢复正常,说明这次安装可以通过镜像完成。之后还要经常安装其他包时,再设置默认镜像;如果只是偶尔遇到慢速下载,保留临时命令就够了,不必改变全局配置。
如果换了镜像仍然失败,先确认虚拟环境是否已激活,再检查运行命令的 Python 是否与项目使用的版本一致。还可以核对包名、版本要求和网络连接。遇到“找不到版本”时,尤其要区分包本身不支持当前 Python 版本、镜像暂未同步和索引地址错误这几种情况。
常见问题与使用注意事项
- 提示找不到版本:先核对包名和版本号,再确认当前 Python 版本是否满足软件包要求。若包刚发布或更新,可以稍后重试;也可以临时切回官方索引,检查是不是镜像同步延迟。
- 遇到证书或网络错误:检查镜像地址是否拼写正确,并排查代理、防火墙或公司网络设置。不要为了绕过报错就随意关闭 HTTPS 验证。
- 想恢复默认设置:运行
python -m pip config unset global.index-url,再执行python -m pip config list确认配置已移除。若设置来自其他配置文件或环境,单独删除这一项后仍需检查实际读取的配置。 - 不同项目需要不同来源:优先在安装命令中使用
-i临时指定索引,避免修改全局配置后影响其他项目。
使用镜像时也要留意软件包来源。安装重要项目依赖前,核对包名和版本,避免把拼写相近但并非所需的包装进环境;不要为了下载快而添加来路不明的索引地址。团队如果对依赖来源有统一要求,可以在项目和部署流程中明确索引配置,避免开发环境与部署环境使用不同来源。
偶尔下载慢,用 -i 临时切换即可;经常需要切换时,再通过 pip config set global.index-url 设置默认镜像。无论采用哪种方式,都建议使用对应 Python 环境的 python -m pip,这样更容易确认软件包装进了哪个环境。