解決 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
     

總結

通過增加超時時間、使用國內鏡像源或優化網絡環境，您應該能解決 ReadTimeoutError。優先推薦設置永久鏡像源（步驟 2），因為它高效且一勞永逸。如果問題依舊，請檢查網絡日志或聯系 IT 支持。記住，此錯誤主要源于網絡因素，而非 pip 本身缺陷。