Introduction

The ReadTimeoutError: HTTPSConnectionPool(host='pypi.python.org', port=443) error means pip could not download a package because the connection to PyPI timed out. This happens when the network is slow, a proxy or firewall interferes, or the PyPI server is temporarily overloaded. The most reliable fix is increasing the timeout with --default-timeout, but you may also need to switch mirrors, configure proxy settings, or retry the installation.

The Error

1pip install some-package
2
3ReadTimeoutError: HTTPSConnectionPool(host='pypi.python.org', port=443):
4Read timed out. (read timeout=15)

The default pip timeout is 15 seconds. If the server does not respond within that window, pip raises this error and aborts the installation.

Fix 1: Increase the Timeout

1# Set timeout to 100 seconds
2pip install some-package --default-timeout=100
3
4# Or set it to a very high value for large packages
5pip install tensorflow --default-timeout=300

You can make this permanent in your pip configuration:

1# ~/.pip/pip.conf (Linux/macOS)
2# %APPDATA%\pip\pip.ini (Windows)
3[global]
4timeout = 100

Fix 2: Use a Different PyPI Mirror

If the main PyPI server is slow in your region, switch to a mirror:

1# Use the official PyPI CDN (default in modern pip)
2pip install some-package -i https://pypi.org/simple/
3
4# Use Tsinghua mirror (fast in China)
5pip install some-package -i https://pypi.tuna.tsinghua.edu.cn/simple
6
7# Use Aliyun mirror
8pip install some-package -i https://mirrors.aliyun.com/pypi/simple/
9
10# Use a trusted host flag if SSL verification fails on mirrors
11pip install some-package -i https://pypi.tuna.tsinghua.edu.cn/simple --trusted-host pypi.tuna.tsinghua.edu.cn

Set a permanent mirror in pip config:

[global]
index-url = https://pypi.org/simple/

Fix 3: Retry the Installation

Transient network issues often resolve on retry:

1# Retry up to 5 times
2pip install some-package --retries 5
3
4# Combine with increased timeout
5pip install some-package --default-timeout=100 --retries 5

Fix 4: Configure Proxy Settings

If you are behind a corporate proxy:

1# Set proxy for pip
2pip install some-package --proxy http://user:[email protected]:8080
3
4# Or set environment variables
5export HTTP_PROXY=http://proxy.example.com:8080
6export HTTPS_PROXY=http://proxy.example.com:8080
7pip install some-package

For pip config:

[global]
proxy = http://user:[email protected]:8080

Fix 5: Download Package Manually

If the connection is consistently failing, download the wheel file manually and install it:

1# Download from a browser or using curl/wget
2curl -O https://files.pythonhosted.org/packages/.../some_package-1.0-py3-none-any.whl
3
4# Install the downloaded file
5pip install some_package-1.0-py3-none-any.whl

Or download to a directory and install from there:

1# Download without installing
2pip download some-package -d ./packages --default-timeout=300
3
4# Install from the downloaded directory
5pip install --no-index --find-links=./packages some-package

Fix 6: Upgrade pip

Older versions of pip may have worse timeout handling and lack retry logic:

1# Upgrade pip itself
2python -m pip install --upgrade pip
3
4# If that also times out, download get-pip.py manually
5curl https://bootstrap.pypa.io/get-pip.py -o get-pip.py
6python get-pip.py

Fix 7: Use a VPN or Different Network

1# Test basic connectivity to PyPI
2curl -I https://pypi.org
3
4# If that times out, the issue is your network, not pip
5# Try:
6# - Switching to mobile hotspot
7# - Using a VPN
8# - Disabling firewall temporarily for testing

Fix 8: Disable IPv6

Some networks have broken IPv6 routing that causes timeouts:

1# Force pip to use IPv4 by setting the environment variable
2export PIP_INDEX_URL=https://pypi.org/simple/
3
4# Or on Linux, prefer IPv4 in /etc/gai.conf
5# Uncomment: precedence ::ffff:0:0/96  100

Pip Configuration File Locations

Common Pitfalls

• Using pypi.python.org instead of pypi.org: The old hostname pypi.python.org redirects to pypi.org. If your pip version is very old, it may still use the old hostname, which can be slower. Upgrade pip to use the modern endpoint.
• Proxy not set for HTTPS: Setting only HTTP_PROXY without HTTPS_PROXY does not cover PyPI connections, which use HTTPS. Always set both environment variables.
• Firewall blocking port 443: Corporate firewalls may block outbound HTTPS. Check with your IT department or try curl https://pypi.org to verify connectivity.
• Large package downloads: Packages like tensorflow, torch, and scipy are hundreds of megabytes. Even a working connection may time out with the default 15-second timeout. Set --default-timeout=300 or higher for large packages.
• Virtual environment isolation: Pip config files inside a virtualenv override global settings. If you set a timeout globally but still get timeouts in a venv, check $VIRTUAL_ENV/pip.conf for conflicting settings.

Summary

• Increase timeout with pip install pkg --default-timeout=100
• Use a PyPI mirror with -i https://mirror-url/simple/
• Add --retries 5 for transient failures
• Configure proxy with --proxy or HTTP_PROXY/HTTPS_PROXY environment variables
• Download packages manually with pip download for persistent connectivity issues
• Upgrade pip to the latest version for better timeout and retry handling