Fix: pip hangs in WSL (IPv6 / gai.conf)

troubleshooting
Author

Alex Guglielmone Nemi

Published

January 13, 2026

Pain Point

pip install hangs in WSL with no useful error, often after it starts fetching from files.pythonhosted.org.

The Rule

If DNS/connection to files.pythonhosted.org hangs but pypi.org works, suspect IPv6 preference + broken IPv6 routing.

Minimal Diagnosis

python -c "import urllib.request; print(urllib.request.urlopen('https://pypi.org/simple/').status)"
# expected: 200
getent hosts pypi.org
# returns quickly
getent hosts files.pythonhosted.org
# may hang

If files.pythonhosted.org hangs, pip will hang. That host is where wheels and sdists are served from.

Fix

Prefer IPv4 for address selection using gai.conf:

sudo tee /etc/gai.conf >/dev/null <<'EOF'
precedence ::ffff:0:0/96  100
EOF

This does not disable IPv6. It changes the precedence so IPv4 is tried first.

Verify

getent hosts files.pythonhosted.org
# should return immediately

Then retry:

pip install ipython

Revert

sudo tee /etc/gai.conf >/dev/null <<'EOF'
# empty override: use glibc defaults
EOF

Notes

If you see multiple stuck installs, clear them before retrying:

pkill -f "python -u -m pip install" || true

Other sources