pip's proxy failures all look alike from a distance. First comes a wall of WARNING: Retrying (Retry(total=4, connect=None, read=None, redirect=None, status=None)) after connection broken by ... lines, five of them. Then an ERROR: Could not find a version that satisfies the requirement sends people looking for a package name problem that does not exist. The real error is inside the parentheses of the first warning. It is one of a small set: ProxyError('Cannot connect to proxy.', ...), Tunnel connection failed: 407 Proxy Authentication Required, SSLError(SSLCertVerificationError(...)), or a ReadTimeoutError. Each is a different problem with a different fix. This guide takes them one at a time, after covering where pip gets its proxy from in the first place.
Search shows the trap at work. Keyword Planner puts "could not find a version that satisfies the requirement" at 480 searches a month worldwide, against 20 for "pip cannot connect to proxy".
How pip finds a proxy
pip makes its network requests through a bundled copy of the requests library, and it inherits that library's habits.
- The
--proxyflag.pip install --proxy http://user:password@proxy.example.com:3128 packageapplies to one command. The argument is a full URL, credentials included. - The configuration file.
pip config set global.proxy http://proxy.example.com:3128writesproxy = ...under[global]in your user configuration. The file is~/.config/pip/pip.confon Linux (older layouts use~/.pip/pip.conf),~/Library/Application Support/pip/pip.confon macOS, and%APPDATA%\pip\pip.inion Windows.pip config debuglists every location pip consults and what each contains. - The
PIP_PROXYvariable. Every pip option can be set asPIP_<OPTION>in the environment, andPIP_PROXYis the proxy. - The standard variables.
HTTP_PROXY,HTTPS_PROXY, andNO_PROXY(upper or lower case) are honored byrequests, so pip uses them while it has no proxy of its own. This is where forgotten proxies live.
- The --proxy flagone command, credentials in the URL
- global.proxy in pip.confevery command, from pip config set
- PIP_PROXYthe same option, from the environment
- HTTP_PROXY, HTTPS_PROXY, NO_PROXYonly while pip has no proxy of its own
each one sets
pip's proxy
A proxy of pip's own switches the standard variables off. Whether it comes from the flag, PIP_PROXY or the configuration file, pip sets trust_env to false on its session. Its copy of requests then ignores HTTP_PROXY, HTTPS_PROXY, NO_PROXY and REQUESTS_CA_BUNDLE. pip's source says so in a comment: an explicit proxy "makes the session ignore environment proxies". Among pip's own sources, the documented order holds: "Command line options override environment variables, which override the values in a configuration file".
We checked the flag against the environment on September 16, 2026, with pip 25.2. With HTTPS_PROXY pointing at a dead address and --proxy naming a working one, the flag won. Newer pip (26.x) also has --no-proxy-env, which ignores the environment variables while still honoring an explicit --proxy. To see what pip is actually using, run pip config list for configured values and env | grep -i proxy for the environment. Between them they account for every proxy pip can see.
How to set and remove the proxy
pip config set global.proxy http://alice:p%40ss@proxy.example.com:3128
pip config list
pip config unset global.proxy
The @ in the password p@ss is written %40, or pip reads everything after the first @ as the hostname. To bypass the proxy for an internal index, keep the proxy and the exclusions together in the environment: HTTPS_PROXY=http://proxy.example.com:3128 with NO_PROXY=pypi.internal.example.com,localhost. pip has no configuration key for exclusions. NO_PROXY also stops working the moment pip has a proxy of its own, which global.proxy above gives it.
For sudo pip install, remember that sudo drops the environment by default, so a proxy in your shell variables vanishes. Use sudo -E pip install ... to keep it, or put the proxy in /etc/pip.conf where root's pip will read it.
The errors
What pip prints inside the retry warning, and the fix for each
| Inside the retry warning | What it means | Fix |
|---|---|---|
ProxyError('Cannot connect to proxy.', NewConnectionError(... Connection refused)) | Nothing listens at the proxy address | Wrong address, port, or network |
NameResolutionError(... Failed to resolve 'proxy.invalid' (... Name or service not known)), with getaddrinfo failed on Windows | The proxy hostname does not resolve here | Off-network leftover; unset it |
ProxyError('Cannot connect to proxy.', OSError('Tunnel connection failed: 407 Proxy Authentication Required')) | Login required at the proxy | Put encoded credentials in the URL |
Tunnel connection failed: 403 Forbidden | The proxy refuses tunnels to PyPI | Policy; ask for PyPI to be allowed, or use an internal mirror |
SSLError(SSLCertVerificationError(... unable to get local issuer certificate)) | An inspecting proxy re-signs HTTPS | --cert or global.cert with the corporate root |
ReadTimeoutError: HTTPSConnectionPool(host='files.pythonhosted.org' ...) | The proxy is slow or stalling | --timeout, --retries, or a better proxy |
ProtocolError('Connection aborted.', BadStatusLine(...)) | The port answered something that is not HTTP | A SOCKS port addressed as http://, or not a proxy at all |
ProxyError('Cannot connect to proxy.', RemoteDisconnected('Remote end closed connection without response')) | The proxy accepted the connection and closed it | An overloaded or half-dead proxy; try another |
Missing dependencies for SOCKS support | A socks:// proxy without PySocks installed | Install PySocks first |
HProxy, pip 25.2 on Python 3.13 against stub proxies on our own machine, September 16, 2026, and our capture of September 2, 2026; nothing left the machine
Cannot connect to proxy
pip never reached PyPI because it could not reach the proxy in front of it. The nested error says why. Connection refused is an address and port where nothing is listening. The port is wrong, the proxy is down, or you are on a network where it is not reachable. Name or service not known (or nodename nor servname provided on macOS, or getaddrinfo failed on Windows) is a hostname that does not resolve on this network. That is the signature of a corporate proxy still configured on a laptop at home. Find the setting with pip config list and env | grep -i proxy, and either unset it or make it conditional on the network. Test the proxy itself with curl, which shares the diagnosis: curl -v -x http://proxy.example.com:3128 https://pypi.org/simple/ -o /dev/null. Our curl proxy errors guide reads its output.
407 in the tunnel
PyPI is HTTPS, so pip asks the proxy for a tunnel, and the proxy answers 407: authenticate first. pip does not prompt; the credentials have to be part of the proxy URL, encoded. They are sent. Against a stub proxy that accepted only one login, the right password in the URL got through and the wrong one came back as 407 again. So a 407 that repeats is a wrong password rather than a client that never sends one. Some proxies insist on NTLM or Kerberos, which pip cannot speak. The workaround there is a local helper that signs in to the corporate proxy for you. It listens on 127.0.0.1 as a plain proxy that pip can use. See 407 Proxy Authentication Required for the encoding and whitelist cases.
403 in the tunnel
The proxy authenticated you and then refused the tunnel to PyPI. That is a policy decision: the organization does not allow direct package installs from the internet. The answers are administrative. Ask for pypi.org and files.pythonhosted.org to be allowed, or use the internal mirror the organization provides through pip config set global.index-url.
The certificate error
CERTIFICATE_VERIFY_FAILED with unable to get local issuer certificate is often followed by Could not fetch URL https://pypi.org/simple/...: There was a problem confirming the ssl certificate. It means an inspecting proxy sits in the middle of the HTTPS connection. The proxy answers with a certificate issued by the organization's own authority rather than PyPI's. Python's bundle does not include that authority. The fixes, from most to least specific:
pip install --cert /path/to/corporate-root.pem package
pip config set global.cert /path/to/corporate-root.pem
export REQUESTS_CA_BUNDLE=/path/to/corporate-root.pem
The first is one command and the second is permanent for pip. The third covers other tools built on requests, and pip only while it has no proxy of its own. With --proxy or global.proxy set, use --cert or global.cert. The file is the authority's root certificate in PEM form, from IT or exported from the system store.
The workaround that circulates everywhere is --trusted-host pypi.org --trusted-host files.pythonhosted.org. It works by telling pip not to verify those hosts at all, which means any machine in the middle can hand you any package. Use it once to confirm the diagnosis, then install the certificate.
Timeouts
A ReadTimeoutError against files.pythonhosted.org through a proxy is a proxy that is slow or stalling on large downloads. pip install --timeout 120 --retries 10 gives it room. A proxy that answers the checker in seconds rather than milliseconds is one to replace.
A SOCKS proxy needs PySocks first
pip can use a SOCKS proxy through requests, with the PySocks package installed and a socks5h:// URL so that the proxy performs the lookups. The catch is ordering. pip cannot install PySocks through a SOCKS proxy it does not yet understand. Install it first with the proxy variables unset or from a downloaded wheel, then configure the proxy. Missing dependencies for SOCKS support is the message when the order is wrong.
The misleading final line
After the retries, pip prints ERROR: Could not find a version that satisfies the requirement package (from versions: none) and ERROR: No matching distribution found for package. The package exists. pip is saying it found no versions because it never received the index. from versions: none is the tell; the real error is in the first warning above it.
Other Python tools
uv, poetry, pipx, and conda each make their own connections. uv and poetry honor the HTTP_PROXY, HTTPS_PROXY, and NO_PROXY variables and use their own certificate settings. For conda, the setting is proxy_servers in .condarc. The environment variables are the one setting that covers all of them. That is the strongest argument for putting the proxy there rather than in pip's own file.
The proxy for pip is not the proxy for your code
Configuring pip's proxy does nothing for the Python you write with the packages it installs. A script using requests or httpx opens its own connections and needs its own proxies argument or environment. Its errors are the same family with different framing. Proxies with Python requests covers that side, including requests.exceptions.ProxyError in scripts and the session settings that keep a scraper on one exit.
What to remember
Read the first retry warning; the last error only repeats the symptom. pip config list and env | grep -i proxy find every proxy in play. Set with --proxy or global.proxy, credentials encoded. Point pip at the corporate authority with --cert rather than reaching for --trusted-host. Install PySocks before a SOCKS proxy. And from versions: none means the index never arrived; the package itself exists.
Sources
- pip user guide, read September 16, 2026: the
--proxyoption "in the form scheme://[user:passwd@]proxy.server:port", theproxykey in a configuration file, the standard environment variables, and--no-proxy-env. - pip source, src/pip/_internal/cli/index_command.py, main branch, read through our server on October 22, 2026: an explicit
--proxyor--no-proxy-env"makes the session ignore environment proxies" (session.trust_env = False). - pip configuration, read October 22, 2026: "Command line options override environment variables, which override the values in a configuration file".
- Google Keyword Planner, worldwide 12-month averages for the searches in the chart, read October 22, 2026.
- Requests documentation, read September 16, 2026: pip's network layer honors
http_proxy,https_proxy,no_proxyandall_proxy, "uppercase variants of these variables are also supported", credentials go in the URL, and SOCKS needs the extra libraries installed withrequests[socks]. - MDN on 407, read September 16, 2026: the request "lacks valid authentication credentials for the proxy server", answered with a
Proxy-Authenticateheader. - RFC 9110 section 9.3.6, June 2022, for the tunnel request every https download makes through a proxy.
- Chromium net_error_list.h, read September 16, 2026, for the same two faults as a browser names them.
- Measured by HProxy on September 16, 2026, with pip 25.2 on Python 3.13: eleven runs against stub proxies on this machine, each failing in one chosen way, so pip never reached an index and nothing left the machine.
