解决 pip 安装包时出现的 ReadTimeoutError 方法 1: 临时使用镜像源（单次安装）

Yn312

1831人浏览 · 2025-08-14 19:10:29

Yn312 · 2025-08-14 19:10:29 发布

解决 pip 安装包时出现的 ReadTimeoutError

当您在使用 pip 安装 Python 包时遇到 pip._vendor.urllib3.exceptions.ReadTimeoutError: HTTPSConnectionPool(host='files.pythonhosted.org', port=443): Read timed out. 错误时，这通常是由于网络问题导致的连接超时。PyPI（Python Package Index）服务器位于国外，国内用户访问时可能因网络不稳定、服务器响应慢或防火墙限制而失败。根据引用分析，主要原因包括：网络连接不稳定、PyPI 服务器繁忙或本地网络配置问题（如代理设置错误）。下面我将一步步指导您解决这个问题，方法已验证可靠，适用于大多数环境。

步骤 1: 增加 pip 的超时时间

pip 默认的超时时间较短（通常为 15 秒），在网络波动时容易触发超时错误。您可以通过命令行参数增加超时时间（例如设为 60 秒或更长）。这能缓解因网络延迟导致的失败。

具体命令：
```
pip install --default-timeout=100 包名
```
例如，安装 requests 包：
```
pip install --default-timeout=100 requests
```
- 如果失败，可以尝试更大的值如 --default-timeout=300（5 分钟）。
- 注意：此方法适用于临时解决，但如果网络问题严重，可能仍需其他方法。

步骤 2: 使用国内镜像源加速下载

国内镜像源（如清华源、阿里云源）能显著提升下载速度和稳定性，因为它们缓存了 PyPI 的包。这是最推荐的解决方案，尤其适合国内用户。

方法 1: 临时使用镜像源（单次安装）
在 pip 命令中直接指定镜像源 URL：

pip install -i https://pypi.tuna.tsinghua.edu.cn/simple 包名

例如，安装 numpy：

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

方法 2: 永久设置镜像源（推荐）
修改 pip 配置文件，避免每次手动输入。
- Windows 系统：
  1. 打开文件资源管理器，输入 %APPDATA% 进入用户目录。
  2. 创建或编辑 pip\pip.ini 文件（如果没有该文件或目录，请手动创建）。
  3. 添加以下内容：
```
[global]
index-url = https://pypi.tuna.tsinghua.edu.cn/simple
trusted-host = pypi.tuna.tsinghua.edu.cn
```
- Linux/macOS 系统：
  1. 在终端运行：
```
mkdir -p ~/.pip
echo -e "[global]\nindex-url = https://pypi.tuna.tsinghua.edu.cn/simple\ntrusted-host = pypi.tuna.tsinghua.edu.cn" > ~/.pip/pip.conf
```
- 常用镜像源：
  - 清华源：https://pypi.tuna.tsinghua.edu.cn/simple
  - 阿里云源：https://mirrors.aliyun.com/pypi/simple
  - 腾讯云源：https://mirrors.cloud.tencent.com/pypi/simple
    设置后，所有 pip 安装命令将自动使用镜像源，减少超时风险。

步骤 3: 检查网络环境

如果以上方法无效，可能是本地网络问题。请检查以下方面：

网络连接：确保您的网络稳定。尝试 ping PyPI 服务器测试连通性：
```
ping files.pythonhosted.org
```
如果延迟高或丢包，考虑切换网络（如从 Wi-Fi 换到有线）。

代理设置：如果您使用代理（如公司网络），确保 pip 配置正确。设置代理环境变量：

export http_proxy=http://your-proxy-ip:port  # Linux/macOS
set http_proxy=http://your-proxy-ip:port     # Windows

或在 pip 命令中直接指定：

pip install --proxy http://your-proxy-ip:port 包名

防火墙和 DNS：关闭临时防火墙或尝试更改 DNS（如使用 8.8.8.8）。引用显示，DNS 解析问题也可能导致超时。

步骤 4: 其他备选方案

重试安装：有时网络波动是暂时的，简单重试即可：
```
pip install 包名
```
使用离线安装：如果网络问题持续，下载包的 .whl 文件手动安装：
1. 访问 PyPI 官网，搜索并下载包文件。
2. 本地安装：
```
pip install 路径/包文件.whl
```