On this page 11 sections
- Every setting, tested
- git: http.proxy is the key, even for HTTPS
- Which setting wins
- One extra 407 on every connection
- socks5 or socks5h
- npm: both spellings work, and the cache lies
- A dead proxy costs 70 seconds
- The cache answers when the network cannot
- pip: the error blames the package
- no_proxy needs two hosts
- SOCKS needs a package pip does not ship
- Reading the errors
- Troubleshooting by symptom
- Proving the proxy is applied
- Where each setting is stored
- Keep the password out of the file
- Where none of this reaches
- How this was tested
To make git use a proxy, set http.proxy. It covers https:// remotes as well, because git has no separate HTTPS key:
git config --global http.proxy http://gateway.example:8000
Do not reach for https.proxy. git accepts it, stores it, prints it back in git config --list, and never reads it, so the clone goes straight to the remote with no warning. npm is the opposite: npm config set proxy and npm config set https-proxy both work. pip takes --proxy or the https_proxy variable. Every claim below was checked on git 2.54.0 (Apple Git-157), npm 11.6.3 on Node 24.2.0, and two pip releases, 25.0 and 26.2.1, against a local Squid 6.13 and a closed port.
Every setting, tested
The test target was HTTPS in every case: a GitHub remote for git, the npm registry, and PyPI. “Honoured” means pointing the setting at a closed port made the command fail and pointing it at Squid put a CONNECT line in the Squid log.
| Setting | git 2.54.0 | npm 11.6.3 | pip 25.0 and 26.2.1 |
|---|---|---|---|
https_proxy (lowercase) |
Honoured | Honoured | Honoured |
HTTPS_PROXY (uppercase) |
Honoured | Honoured | Honoured |
http_proxy or HTTP_PROXY only |
Ignored | Ignored | Ignored |
ALL_PROXY |
Honoured | Ignored | Honoured |
| The tool’s own option | http.proxy |
proxy or https-proxy |
--proxy, or proxy = in pip.conf |
| An HTTPS-named variant of that option | https.proxy: silently ignored |
https-proxy works, and wins over proxy |
None exists |
no_proxy in the environment |
Honoured, even over http.proxy |
Honoured | Honoured, needs both PyPI hosts |
| The tool’s own bypass | http.<url>.proxy "" |
noproxy |
--no-proxy-env, 26.2 and later only |
socks5h:// proxy URL |
Works | Works | Only with PySocks installed |
Three rows deserve a second look. All three tools ignore http_proxy when the endpoint is HTTPS, which is correct and still catches people who set only that one. ALL_PROXY works for git and pip and does nothing for npm, so a shell that relies on it routes two of the three. And the no_proxy row for git is not what most people expect: an exemption in the environment beat a proxy written into git’s own config.
git: http.proxy is the key, even for HTTPS
With http.proxy pointed at 127.0.0.1:9, git ls-remote failed in 0.03 seconds. With https.proxy pointed at the same port it returned the remote’s HEAD in 0.6 seconds, having connected directly. git has no such key. Its proxy setting is http.proxy regardless of the URL scheme, plus the URL-scoped form http.<url>.proxy, plus remote.<name>.proxy per remote.
# Only this host goes through the proxy
git config --global http.https://github.com/.proxy http://gateway.example:8000
# Everything except this host
git config --global http.proxy http://gateway.example:8000
git config --global http.https://internal.example/.proxy ""
Both forms were run against a closed port. The URL-scoped proxy alone failed for github.com, as it should. The global proxy plus an empty URL-scoped value for github.com succeeded, which confirms the empty string means “no proxy for this one”.
Which setting wins
git’s manual describes http.proxy as an override of the http_proxy, https_proxy and all_proxy variables. The test agreed in both directions: config pointing at Squid with https_proxy pointing at a closed port succeeded through Squid, and the reverse failed on the closed port. The exception is no_proxy. With http.proxy set to the closed port and no_proxy=github.com exported, the command succeeded and Squid logged nothing. If git ignores your configured proxy for one host, check the environment for a no_proxy line before you check the config.
One extra 407 on every connection
With credentials in the proxy URL, Squid logged two lines per connection:
TCP_DENIED/407 CONNECT github.com:443 -
TCP_TUNNEL/200 CONNECT github.com:443 pwtest
That is git’s default http.proxyAuthMethod, anyauth, which sends an unauthenticated request first to learn which scheme the proxy wants. Setting the method removes the probe:
git -c http.proxyAuthMethod=basic ls-remote https://github.com/octocat/Hello-World.git HEAD
# Squid logged a single line:
# TCP_TUNNEL/200 CONNECT github.com:443 pwtest
Every probe is a 407 in the proxy’s log. On a provider that alerts on authentication failures, or counts them against you, anyauth looks like a client getting its password wrong half the time. npm and pip sent credentials on the first request, one Squid line each.
socks5 or socks5h
git passes the proxy URL to libcurl, so SOCKS works. The scheme decides who resolves the hostname. Our logging SOCKS5 server recorded this for the same ls-remote:
http.proxy=socks5h://user:pass@127.0.0.1:31901 CONNECT atyp=DOMAIN target=github.com:443
http.proxy=socks5://user:pass@127.0.0.1:31901 CONNECT atyp=IPv4 target=140.82.121.3:443
With socks5:// the lookup happened on the laptop and the proxy received a bare address. Use socks5h:// unless you have a reason not to. The curl proxy guide covers the same split from curl’s side.
npm: both spellings work, and the cache lies
npm config set proxy http://gateway.example:8000
npm config set https-proxy http://gateway.example:8000
npm config set noproxy registry.internal.example,localhost
proxy on its own was applied to the HTTPS registry. With both set to different values, https-proxy won. The exemption list is spelled noproxy, one word, and the environment’s no_proxy worked too.
A dead proxy costs 70 seconds
Every npm failure against a closed or unresolvable proxy took between 70.1 and 70.2 seconds before printing an error. That is the retry policy: npm’s documented defaults are fetch-retries 2, fetch-retry-mintimeout 10 seconds and fetch-retry-maxtimeout 60 seconds, and 10 plus 60 is what we measured. A 407 is not retried and came back in 0.25 seconds. When you are debugging, turn the retries off:
npm view express version --https-proxy http://127.0.0.1:9 --fetch-retries=0
# npm error code ECONNREFUSED (0.20 s instead of 70)
The cache answers when the network cannot
We warmed a cache directory through Squid, then pointed the proxy at a closed port and reused the cache. npm view express version printed 5.3.0 in 0.10 seconds. Adding --prefer-online did not change that. npm install is-number@7.0.0 reported added 1 package in 87ms through the same dead proxy. None of these touched the network, so none of them tested the proxy. Point --cache at an empty temporary directory whenever you are checking proxy behaviour.
pip: the error blames the package
# Per command
pip install --proxy http://gateway.example:8000 requests
# Persistent, in pip.conf
[global]
proxy = http://gateway.example:8000
# pip 26.2 and later: ignore proxy variables inherited from the shell
pip install --no-proxy-env requests
--no-proxy-env arrived in pip 26.2, released on 29 July 2026. pip 25.0 rejects it with no such option: --no-proxy-env, so scripts that must run on both should unset the variables instead.
no_proxy needs two hosts
pip fetches the index from one domain and the files from another. With https_proxy pointed at Squid and no_proxy=pypi.org, Squid logged exactly one tunnel:
TCP_TUNNEL/200 CONNECT files.pythonhosted.org:443 -
The index lookup went direct and the download still went through the proxy. Exempt both, no_proxy="pypi.org,files.pythonhosted.org", or you get the half-configuration that fails only on networks where the proxy matters.
SOCKS needs a package pip does not ship
pip 25.0 downloaded six through socks5h:// without complaint, and the SOCKS log showed both pypi.org and files.pythonhosted.org arriving as hostnames. That worked only because PySocks 1.7.1 happened to be installed beside it. pip 26.2.1 on Python 3.15, with no PySocks, exited with status 2 and a traceback ending in:
pip._vendor.requests.exceptions.InvalidSchema: Missing dependencies for SOCKS support.
The fix is to install PySocks into the environment pip runs from. If the SOCKS proxy is your only route to PyPI, fetch that one wheel another way first.
Reading the errors
Each line below was produced on purpose. “Closed port” is 127.0.0.1:9; “wrong password” is Squid returning 407; “bad host” is no-such-proxy.invalid.
| Tool and fault | What it printed | Time |
|---|---|---|
| git, closed port | fatal: unable to access '...': Failed to connect to 127.0.0.1 port 9 after 0 ms: Couldn't connect to server |
0.03 s |
| git, bad host | fatal: unable to access '...': Could not resolve proxy: no-such-proxy.invalid |
0.03 s |
| git, wrong password | fatal: unable to access '...': CONNECT tunnel failed, response 407 |
0.03 s |
git, https:// written for a plain proxy |
LibreSSL/3.3.6: error:1404B42E:SSL routines:ST_CONNECT:tlsv1 alert protocol version |
0.03 s |
| npm, closed port | npm error code ECONNREFUSED and reason: connect ECONNREFUSED 127.0.0.1:9 |
70.1 s |
| npm, bad host | npm error code ENOTFOUND and getaddrinfo ENOTFOUND no-such-proxy.invalid |
70.2 s |
| npm, wrong password | npm error code E407 and 407 Proxy Authentication Required - GET https://registry.npmjs.org/express |
0.25 s |
| pip 25.0, closed port | Five WARNING: Retrying lines naming ProxyError('Cannot connect to proxy.', ...), then the package error |
8.1 s |
| pip 26.2.1, closed port | Five WARNING: Retrying lines naming NewConnectionError("HTTPSConnection(host='127.0.0.1', port=9) ..."), then the package error |
7.9 s |
| pip 26.2.1, wrong password | OSError('Tunnel connection failed: 407 Proxy Authentication Required') in each warning |
8.0 s |
pip, either version, --retries 0 |
Only the package error, nothing else | 0.4 to 0.6 s |
Every pip failure ended with the same two lines:
ERROR: Could not find a version that satisfies the requirement six (from versions: none)
ERROR: No matching distribution found for six
Those read exactly like a misspelled package. The only clue sits above them, in the retry warnings, and it changed between releases. pip 25.0 says ProxyError. pip 26.2.1, in our runs, no longer prints the word “proxy” for a dead proxy at all; it names a connection to 127.0.0.1:9, which you have to recognise as your proxy’s address. With --retries 0 the warnings disappear and nothing on screen points at the network. If a package manager says a package does not exist and you are behind a proxy, test the proxy before the package name. For what the 407 itself means and why it never reaches the registry, see 403 vs 407 vs 429.
Troubleshooting by symptom
| Symptom | Most likely cause | Check |
|---|---|---|
| git clones fine but the proxy log is empty | https.proxy set instead of http.proxy, or a no_proxy entry covering the host |
git config --show-origin --get-regexp proxy, then env | grep -i no_proxy |
| Proxy log shows a 407 before every successful tunnel | git’s anyauth probe |
git config --global http.proxyAuthMethod basic |
| git fails with a LibreSSL or OpenSSL protocol error | The proxy URL says https:// but the proxy speaks plain HTTP |
Change the scheme to http:// |
| npm hangs for about a minute, then fails | Proxy unreachable, and npm is retrying | Rerun with --fetch-retries=0 |
| npm works through a proxy you know is down | Answered from the cache | Rerun with --cache $(mktemp -d) |
npm ignores your ALL_PROXY |
npm does not read it | Set https_proxy or https-proxy |
| pip says no version satisfies the requirement | Proxy refused, unreachable or rejecting the password | Scroll up to the WARNING: Retrying lines |
| pip index works, downloads fail or bypass the proxy | no_proxy lists only one of the two PyPI hosts |
List both pypi.org and files.pythonhosted.org |
pip prints Missing dependencies for SOCKS support |
PySocks absent from pip’s environment | Install PySocks there, or use an HTTP proxy |
Proving the proxy is applied
A tool that ignores your setting succeeds quietly, which looks identical to a tool that used the proxy. Point the setting at a port where nothing listens. A setting that is honoured must fail:
# If any of these succeed, that tool ignored the setting
https_proxy=http://127.0.0.1:9 git ls-remote https://github.com/octocat/Hello-World.git
https_proxy=http://127.0.0.1:9 pip download six --no-deps --no-cache-dir --retries 0 -d /tmp/x
https_proxy=http://127.0.0.1:9 npm view express version --cache "$(mktemp -d)" --fetch-retries=0
Run the same three with the variable unset first. If they fail then too, you have a network problem rather than a proxy result. For git, the trace shows the tunnel being built. These are the relevant lines from GIT_TRACE_CURL=1 GIT_TRACE_CURL_NO_DATA=1 through our Squid:
== Info: Connected to 127.0.0.1 (127.0.0.1) port 31291
== Info: Establish HTTP proxy tunnel to github.com:443
=> Send header: CONNECT github.com:443 HTTP/1.1
<= Recv header: HTTP/1.1 200 Connection established
== Info: CONNECT tunnel established, response 200
The strongest check is the proxy’s own log. A tool that never contacted the proxy leaves nothing there, whatever its exit code says. The same closed-port method works for every runtime in the environment-variable guide.
Where each setting is stored
| Tool | Per-user file | How to find it |
|---|---|---|
| git | ~/.gitconfig, or $XDG_CONFIG_HOME/git/config |
git config --global --list --show-origin |
| npm | ~/.npmrc |
npm config get userconfig |
| pip | ~/.config/pip/pip.conf, or ~/.pip/pip.conf |
pip config debug |
Each also has a system-wide layer: /etc/gitconfig, an npmrc beside the npm installation, and a global pip.conf. On a machine somebody else set up, a proxy you cannot find in your own files usually sits in one of those. --show-origin and pip config debug report which file a value came from, which turns “why is it still using the old proxy” into a one-line answer.
Keep the password out of the file
A proxy URL with inline credentials ends up in git config --list, in ~/.npmrc as plain text, in shell history and in any CI log that echoes the environment. git has a documented way around it: give the proxy URL a user name and no password, and git asks its credential helper for the rest.
git config --global http.proxy http://pwtest@127.0.0.1:31281
git ls-remote https://github.com/octocat/Hello-World.git HEAD
# fatal: could not read Password for 'http://pwtest@127.0.0.1:31281': terminal prompts disabled
# Store the proxy password with the credential helper instead
printf 'protocol=http\nhost=127.0.0.1:31281\nusername=pwtest\npassword=%s\n\n' "$PROXY_PASS" \
| git credential approve
git ls-remote https://github.com/octocat/Hello-World.git HEAD
# 7fd1a60b01f91b314f59955a4e4d4e80d8edf11d HEAD
After that, git config --list shows http.proxy=http://pwtest@127.0.0.1:31281 and no secret. Our test used the store helper, which writes plain text to its own file; on macOS the osxkeychain helper keeps it in the system keychain instead. npm and pip have no equivalent, so supply the URL in an environment variable at run time rather than writing it into .npmrc or pip.conf. Where the provider supports it, an address allow-list means no secret travels with the request at all. The general rules for proxy authentication apply here too.
Where none of this reaches
- A container does not inherit your shell. Exported variables are not passed to
docker rununless you name them, a build runs each step in its own container again, and pulling the image is a third case, made by the daemon. - A service manager does not inherit your login shell. A unit started by systemd, or a job started by cron, gets the environment it is given. Exporting a variable in a profile and restarting the service changes nothing.
- CI runners start clean. The proxy that works on your laptop is absent in the pipeline unless the pipeline sets it, which is why “works locally, fails in CI” is the standard symptom.
Docker itself is absent from this page. We could not run a daemon on the test machine, and we do not publish configuration we have not executed. Language clients behave differently again: see proxies in Python and proxies in Node.js.
How this was tested
Run on macOS on 21 October 2026 with git 2.54.0 (Apple Git-157, whose TLS errors come from LibreSSL 3.3.6), npm 11.6.3 on Node 24.2.0, pip 25.0 on Python 3.9.6 and pip 26.2.1 on Python 3.15.0. The proxies were Squid 6.13 on 127.0.0.1, one port open and one requiring basic authentication, and a small logging SOCKS5 server that records whether it received a hostname or an address. Targets: git ls-remote https://github.com/octocat/Hello-World.git HEAD, npm view express version, and pip download six --no-deps --no-cache-dir.
Each of the 64 cases ran with proxy variables cleared from the environment, a throwaway GIT_CONFIG_GLOBAL with GIT_CONFIG_NOSYSTEM=1, an empty npm user config and a fresh npm cache, and PIP_CONFIG_FILE=/dev/null. Each tool had a no-proxy control that succeeded. The cache and credential-helper cases were run separately, by hand, with the commands shown. Timings are single runs on one machine.
An earlier version of this page, tested on git 2.50.1 and pip 25.0, said pip’s output never mentions the proxy. That was true only of the final two lines. The retry warnings above them do, in pip 25.0, and we have corrected it.
Frequently asked questions
How do I set a proxy for git?
Why does git config https.proxy not work?
How do I set a proxy for npm?
pip says it cannot find the package. Is that a proxy problem?
Why did my npm proxy test pass when the proxy was down?
Does pip support SOCKS proxies?
Sources
- git config: http.proxy, http.proxyAuthMethod and http.<url>.* matching
- gitcredentials: how git asks a helper for a missing password
- npm config: proxy, https-proxy, noproxy and the fetch-retry defaults
- pip user guide: --proxy, proxy environment variables and --no-proxy-env
- pip changelog: --no-proxy-env added in pip 26.2, 2026-07-29
- curl manual: proxy URL schemes, socks5h and the variables libcurl reads