换用国内镜像源是解决pip安装超时问题的直接高效方法,包括临时指定源、永久配置windows/linux/macos全局源、pip config命令设置及延长超时阈值五种方案。

如果您执行 pip install 命令时反复出现“Read timed out”“Connection to pypi.org timed out”或长时间卡在“Collecting package”阶段,则大概率不是本地网络中断,而是 pip 仍在尝试连接远在境外的默认源 https://pypi.org/simple——该地址在国内解析慢、TLS握手延迟高、传输易丢包。换用国内镜像源是直接且高成功率的应对方式。以下是多种可行方案:
一、临时指定镜像源(单次安装生效)
此方法不修改任何配置,适用于快速验证或仅安装某一个包,避免因镜像配置错误导致后续异常。命令中显式声明镜像地址与可信主机,绕过证书校验拦截。
1、在终端中输入完整命令,注意末尾空格及斜杠格式:pip install -i https://pypi.tuna.tsinghua.edu.cn/simple/ --trusted-host pypi.tuna.tsinghua.edu.cn requests
2、若需安装其他库(如 numpy),将末尾 “requests” 替换为对应包名即可
3、可替换为其他国内镜像地址,例如阿里云源:pip install -i https://mirrors.aliyun.com/pypi/simple/ --trusted-host mirrors.aliyun.com 包名
二、永久配置全局镜像源(Windows系统)
此方法通过创建标准 pip 配置文件,使所有后续 pip install 命令自动使用指定镜像,无需重复添加参数。关键在于路径与文件名必须严格符合 pip 的 Windows 查找规则。
1、按下 Win + E 打开文件资源管理器,在地址栏粘贴并回车:%APPDATA%
2、进入该目录后,检查是否存在名为 pip 的文件夹;如无,则右键 → 新建 → 文件夹,并命名为 pip
3、进入 pip 文件夹,右键 → 新建 → 文本文档,打开后粘贴以下两行内容:
[global]
index-url = https://pypi.tuna.tsinghua.edu.cn/simple/
trusted-host = pypi.tuna.tsinghua.edu.cn
4、将该文本文档重命名为 pip.ini,操作时需确保已开启“显示文件扩展名”,并把 .txt 后缀完全删除
三、永久配置全局镜像源(Linux/macOS系统)
此方法通过在用户主目录下建立标准 pip 配置路径和文件,实现所有虚拟环境与系统级 pip 调用统一走国内源。配置位置与权限需准确,否则 pip 将忽略该文件。
1、在终端中执行创建目录命令:mkdir -p ~/.pip
2、执行写入配置命令:echo "[global]\nindex-url = https://pypi.tuna.tsinghua.edu.cn/simple/\ntrusted-host = pypi.tuna.tsinghua.edu.cn" > ~/.pip/pip.conf
3、确认文件生成成功:运行 cat ~/.pip/pip.conf,应完整显示上述三行内容
4、如当前用户为 root 或使用 sudo 运行 pip,还需为 root 用户单独配置:将相同内容写入 /root/.pip/pip.conf
四、使用 pip config 命令行工具设置(跨平台通用)
此方法依赖 pip 21.0+ 版本内置的配置管理子命令,不涉及手动编辑文件,适合对文件系统路径不熟悉或需脚本化部署的场景。命令会自动定位并更新正确的配置文件位置。
1、在终端中运行:pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple/
2、紧接着运行:pip config set global.trusted-host pypi.tuna.tsinghua.edu.cn
3、验证是否生效:运行 pip config list,输出中应包含刚设置的两项
4、若提示 “No such key”,说明 pip 版本过低,需先执行 python -m pip install --upgrade pip
五、延长超时阈值作为辅助手段
当镜像源本身响应偶发波动(如 CDN 节点瞬时拥塞),单纯换源可能仍短暂失败。此时可同步提升 pip 的连接与读取等待上限,避免因短时延迟被误判为超时。
1、临时延长单次安装超时:在安装命令末尾添加 --default-timeout=100,例如 pip install requests --default-timeout=100
2、永久设置超时值:运行 pip config set global.timeout 100
3、注意 timeout 单位为秒,数值不宜超过 120,过高可能导致故障响应迟滞
4、该设置需与镜像源配置共存才有效;若仅设 timeout 而未换源,仍会持续连接国外服务器










