在使用 Python 进行日常开发或部署大模型、深度学习项目时，我们经常需要通过 pip 安装各种第三方依赖包。然而，由于官方 PyPI 服务器位于海外，在没有科学上网的环境下，pip install 经常会遇到下载缓慢、卡死甚至直接报错中断的情况。

常见的报错信息包括：

• socket.timeout: The read operation timed out
• ConnectionResetError: [Errno 104] Connection reset by peer
• WARNING: Retrying (Retry(total=4, ...))
• pip._vendor.urllib3.exceptions.ReadTimeoutError

本文将系统化地梳理 pip install 超时的原因，提供临时换源、永久换源的多种配置方法，并附带一键自动测速并切换最快国内源的工具脚本。见文末

---

一、 常见 pip 超时与网络报错场景分析

1. 经典超时报错（ReadTimeoutError）

pip._vendor.urllib3.exceptions.ReadTimeoutError: HTTPSConnectionPool(host='files.pythonhosted.org', port=443): Read timed out.

• 原因分析：这是最常见的超时报错。国内访问官方 files.pythonhosted.org 节点的连接质量不佳，导致在规定的时间内（默认一般为 15 秒）没有读取到数据。
• 应急办法：在安装命令后加上 --default-timeout=100 延长等待时间。

2. SSL 证书校验失败（SSLError）

WARNING: Retrying (Retry(total=4, ...)) after connection broken by 'SSLError(SSLCertVerificationError(1, '[SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed...'))'

• 原因分析：在使用某些公司内网、学校网关，或者开启了全局代理软件时，SSL 握手可能会被拦截或篡改，导致 pip 安全校验不通过。
• 应急办法：换源时必须同时使用 --trusted-host 参数将镜像源设为受信任主机。

---

二、 解决方案一：临时指定国内镜像源（一秒起效）

如果只是临时下载某一个库，可以直接在 pip install 后面加上 -i 参数来指定国内的镜像源。

1. 临时换源命令格式：

pip install <包名> -i <国内镜像源地址>

2. 常用国内优秀 PyPI 镜像源列表：

机构名称	镜像源地址（推荐收藏）
清华大学	https://pypi.tuna.tsinghua.edu.cn/simple
阿里云	https://mirrors.aliyun.com/pypi/simple/
腾讯云	https://mirrors.cloud.tencent.com/pypi/simple/
中科大	https://pypi.mirrors.ustc.edu.cn/simple/
华为云	https://mirrors.huaweicloud.com/repository/pypi/simple/

⚠️ 注意：如果遇到上文提到的 SSLError，在临时安装时需要加上 --trusted-host 参数。例如使用清华源：

pip install numpy -i https://pypi.tuna.tsinghua.edu.cn/simple --trusted-host pypi.tuna.tsinghua.edu.cn

---

三、 解决方案二：永久配置国内镜像源（一劳永逸）

如果希望以后每次运行 pip install 都自动使用国内镜像，推荐进行永久配置。目前有“命令行自动配置”和“手动创建配置文件”两种方法。

方法 1：使用 pip config 命令一键配置（推荐）

这是最现代、最不容易出错的方法，支持所有操作系统。

1. 配置为清华源：

   pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple
   

2. （可选）如果遇到 SSL 报错，追加信任主机：

   pip config set global.trusted-host pypi.tuna.tsinghua.edu.cn
   

3. 验证配置是否成功：

   pip config list
   

   如果成功输出 global.index-url='...'，则说明永久换源成功。

---

方法 2：手动创建配置文件

如果在某些老旧 Python 环境或受限服务器中无法使用 pip config 命令，可以手动创建配置文件。

1. Windows 系统

1. 按下 Win + R 键，输入 %appdata% 并回车。
2. 在打开的目录中新建一个名为 pip 的文件夹。
3. 在 pip 文件夹下新建一个文本文档，命名为 pip.ini（确保后缀是 .ini 而不是 .txt）。
4. 写入以下内容并保存：

   [global]
   index-url = https://pypi.tuna.tsinghua.edu.cn/simple
   trusted-host = pypi.tuna.tsinghua.edu.cn
   timeout = 120
   

2. Linux / macOS 系统

1. 在用户家目录下创建 .pip 隐藏文件夹：

   mkdir -p ~/.pip
   

2. 创建并编辑 pip.conf 配置文件：

   nano ~/.pip/pip.conf
   

3. 写入以下内容，保存并退出：

   [global]
   index-url = https://pypi.tuna.tsinghua.edu.cn/simple
   trusted-host = pypi.tuna.tsinghua.edu.cn
   timeout = 120
   

---

四、 进阶网络故障排查：换源后依然超时怎么办？

如果在换了国内源之后，依然频繁提示 Connection timed out，请检查以下两点：

1. 代理软件（VPN / 科学上网）冲突

• 现象：开启全局代理后，访问国内镜像源（如清华源）反而变慢，或者提示 SSL 证书错误。
• 解决办法：
  • 将代理软件设为“规则模式/PAC模式”，避免国内流量走国外节点。
  • 或者临时关闭代理软件。
  • 或者直接在终端清理代理相关的系统环境变量：

    # Windows CMD
    set http_proxy=
    set https_proxy=
    
    # Linux / macOS / Git Bash
    unset http_proxy
    unset https_proxy
    

2. 缓存文件损坏干扰

• 现象：即使更换了配置，下载依然在某个进度卡死，或者提示 HASH mismatch。
• 解决办法：清除 pip 缓存后重新尝试。

  pip cache purge
  

---

五、 附：一键自动配置与测速切换脚本工具

为了节省大家手动修改配置的时间，我编写了以下几套一键配置工具。

1. Windows 一键换源批处理脚本 (pip_win_setup.bat)

新建一个文本文档，将以下代码复制进去，保存并将后缀修改为 .bat，双击运行即可：

@echo off
chcp 65001 >nul
echo ====================================================
echo         PIP Windows 国内镜像源一键配置工具
echo ====================================================
echo.
echo 请选择要更换的国内镜像源：
echo [1] 阿里云 (推荐)
echo [2] 清华大学 (推荐)
echo [3] 腾讯云
echo [4] 华为云
echo [5] 恢复官方默认源
echo.

set /p choice="请输入数字选项 (1-5): "

if "%choice%"=="1" (
    pip config set global.index-url https://mirrors.aliyun.com/pypi/simple/
    pip config set global.trusted-host mirrors.aliyun.com
    echo [成功] 已永久切换为 阿里云 镜像源！
) else if "%choice%"=="2" (
    pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple
    pip config set global.trusted-host pypi.tuna.tsinghua.edu.cn
    echo [成功] 已永久切换为 清华大学 镜像源！
) else if "%choice%"=="3" (
    pip config set global.index-url https://mirrors.cloud.tencent.com/pypi/simple/
    pip config set global.trusted-host mirrors.cloud.tencent.com
    echo [成功] 已永久切换为 腾讯云 镜像源！
) else if "%choice%"=="4" (
    pip config set global.index-url https://mirrors.huaweicloud.com/repository/pypi/simple/
    pip config set global.trusted-host mirrors.huaweicloud.com
    echo [成功] 已永久切换为 华为云 镜像源！
) else if "%choice%"=="5" (
    pip config unset global.index-url
    pip config unset global.trusted-host
    echo [成功] 已恢复官方默认源！
) else (
    echo [错误] 输入选项无效，未做任何更改。
)

echo.
echo 当前实际生效的 pip 配置如下：
pip config list
echo.
pause

---

2. Python 智能自动测速并换源脚本 (pip_speed_test.py)

这是最实用的高级工具。运行该脚本后，它会自动检测五个国内源的延迟，并自动将你的 pip 永久切换为当前网络下延迟最低的那一个！

在终端运行以下脚本（无需安装第三方依赖）：

import os
import time
import urllib.request
import subprocess

# 定义待测速的镜像源
MIRRORS = {
    "清华大学": {
        "url": "https://pypi.tuna.tsinghua.edu.cn/simple",
        "host": "pypi.tuna.tsinghua.edu.cn"
    },
    "阿里云": {
        "url": "https://mirrors.aliyun.com/pypi/simple/",
        "host": "mirrors.aliyun.com"
    },
    "腾讯云": {
        "url": "https://mirrors.cloud.tencent.com/pypi/simple/",
        "host": "mirrors.cloud.tencent.com"
    },
    "中科大": {
        "url": "https://pypi.mirrors.ustc.edu.cn/simple/",
        "host": "pypi.mirrors.ustc.edu.cn"
    },
    "华为云": {
        "url": "https://mirrors.huaweicloud.com/repository/pypi/simple/",
        "host": "mirrors.huaweicloud.com"
    }
}

def test_speed(name, info):
    """测试指定镜像源的响应时间"""
    url = info["url"]
    print(f"正在对 [{name}] 进行网络测速...", end="", flush=True)
    start_time = time.time()
    try:
        # 只请求头部信息，超时设为5秒
        req = urllib.request.Request(url, method="HEAD")
        with urllib.request.urlopen(req, timeout=5) as response:
            latency = (time.time() - start_time) * 1000  # 毫秒
            print(f" 延迟: {latency:.2f} ms")
            return latency
    except Exception as e:
        print(" 连接超时或请求失败！")
        return float('inf')

def set_pip_source(name, info):
    """通过命令行配置 pip 源"""
    url = info["url"]
    host = info["host"]
    try:
        subprocess.run(["pip", "config", "set", "global.index-url", url], check=True, stdout=subprocess.DEVNULL)
        subprocess.run(["pip", "config", "set", "global.trusted-host", host], check=True, stdout=subprocess.DEVNULL)
        print(f"\n[配置成功] 您的 pip 已成功永久切换至当前最快的镜像源: 【{name}】")
    except Exception as e:
        print(f"\n[错误] 配置失败，请确认系统已配置 pip 环境变量！详细错误: {e}")

if __name__ == "__main__":
    print("====================================================")
    print("       Python pip 国内镜像源自动测速与优化配置工具")
    print("====================================================")
    print()
    
    results = {}
    for name, info in MIRRORS.items():
        latency = test_speed(name, info)
        results[name] = latency
        
    # 过滤掉失败的源并排序
    valid_results = {k: v for k, v in results.items() if v != float('inf')}
    
    if not valid_results:
        print("\n[错误] 所有国内镜像源均连接超时，请检查您的网络连接！")
    else:
        best_mirror = min(valid_results, key=valid_results.get)
        print(f"\n测速完毕！当前网络环境下延迟最低的源为: 【{best_mirror}】 ({valid_results[best_mirror]:.2f} ms)")
        set_pip_source(best_mirror, MIRRORS[best_mirror])

大家在配置环境或安装依赖包时，若遇到其他奇怪的报错或网络问题，欢迎在评论区共同探讨！
链接：https://pan.quark.cn/s/27b18aec9d0a
提取码：YtDQ

---