How to Set Up a Proxy for Git: http.proxy, SOCKS5 and SSH Remotes

What a proxy changes and what it does not

A proxy changes only the network path between your computer and the Git server. It does not change the rules of the Git hosting service you use, who may use it or where. Git itself works with any ordinary HTTP or SOCKS5 proxy that only forwards traffic.

Two kinds of remotes need two settings

A remote is the address Git talks to. Run git remote -v to see yours. If it starts with https:// (or http://), Git talks through the curl library and the http.proxy setting applies. If it starts with git@ or ssh://, Git hands the connection to ssh and http.proxy is ignored; that case is in the SSH section below. If you are not sure which you have, the simplest way to use a proxy is to switch the remote to its https:// address.

One proxy for all HTTPS remotes

The git-config page describes http.proxy as an override of the proxy that is normally set with the http_proxy, https_proxy and all_proxy environment variables. It is the only key you need, and it covers https:// addresses too. The value is [protocol://][user[:password]@]proxyhost[:port]. The second command in the example prints the value back, which is the quickest way to see what is set.

• Sources:
• Git docs: git-config (http.proxy, http.<url>.*, remote.<name>.proxy)

One proxy for all HTTPS remotes: example

git config --global http.proxy http://USERNAME:PASSWORD@HOST:PORT
git config --global --get http.proxy

Replace HOST, PORT, USERNAME and PASSWORD with the values from My assets.

Username and password

If the username or password contains special characters, percent-encode them in the address: @ becomes %40, : becomes %3A, / becomes %2F, # becomes %23 and % becomes %25. Copying the values from My assets is safer than typing them. The git-config page also allows a user name without a password, for example http://USERNAME@HOST:PORT: Git then asks for the password the way it does for other credentials, so the password is not stored in the file. Note that git config --global writes to ~/.gitconfig as plain text, so a password inside the address can be read by anyone who can read that file.

• Sources:
• Git docs: git-config (http.proxy, http.<url>.*, remote.<name>.proxy)

A different proxy, or none, for one host

Any http.* option can be applied to some URLs only, by putting the URL in the key: http.<url>.proxy. The scheme and the host must match the remote exactly, and a longer match wins. This is handy when only GitHub needs the proxy and your company's own Git server must be reached directly. Giving remote.<name>.proxy an empty string disables the proxy for that one remote, which the git-config page states; it does not say what an empty http.<url>.proxy does, so use the remote.<name>.proxy form when you need to switch the proxy off for a single remote.

• Sources:
• Git docs: git-config (http.proxy, http.<url>.*, remote.<name>.proxy)

A different proxy for one host: example

git config --global http.https://github.com/.proxy http://USERNAME:PASSWORD@HOST:PORT
git config remote.origin.proxy ""

The first line sets the proxy for github.com only. The second line turns it off for the remote named origin in the current repository.

Try it for one command only

To try a proxy without saving anything, pass the setting for a single run with git -c. Nothing is written to ~/.gitconfig, and the password stays out of the config file (it is still visible in the command line while the command runs).

Try it for one command only: example

git -c http.proxy=http://USERNAME:PASSWORD@HOST:PORT clone https://github.com/git/git.git

Replace HOST, PORT, USERNAME and PASSWORD with the values from My assets.

SOCKS5 and socks5h

Git hands the proxy string to curl, and the Git documentation points to the syntax curl understands. The curl documentation lists socks5:// and socks5h://; with socks5h:// the proxy, not your computer, resolves the website name. Use socks5h:// unless you have a reason to resolve names locally. The Git page does not list the schemes itself, so confirm it works with the check below on your Git version.

• curl proxy setup guide
• SOCKS5 proxies page

• Sources:
• Git docs: git-config (http.proxy, http.<url>.*, remote.<name>.proxy)
• libcurl docs: CURLOPT_PROXY

SOCKS5 and socks5h: example

git config --global http.proxy socks5h://USERNAME:PASSWORD@HOST:PORT

Replace HOST, PORT, USERNAME and PASSWORD with the values from My assets.

How to switch the proxy off

Remove the key with --unset. If you set the same key in several places, use --unset-all, and run git config --global --list to confirm that no http.proxy line is left. The proxy environment variables http_proxy, https_proxy and all_proxy are also read, as the git-config page says, so unset those in the shell too if the proxy keeps coming back.

• Sources:
• Git docs: git-config (http.proxy, http.<url>.*, remote.<name>.proxy)

How to switch the proxy off: example

git config --global --unset http.proxy
git config --global --unset-all http.https://github.com/.proxy

Run git config --global --list afterwards to see what is left.

SSH remotes (git@... and ssh://...)

http.proxy does nothing for SSH remotes, because Git runs ssh and ssh makes the connection. In ssh you set a ProxyCommand: a command that opens the connection to the server for ssh, with %h standing for the remote host and %p for the remote port, as the ssh_config manual explains. The manual's own example uses nc with -X connect for an HTTP proxy. ProxyJump is not a replacement: it is described only for jumping through another SSH host, not through a SOCKS or HTTP proxy.

For a proxy with a username and password you need a tool that can send them. The OpenBSD nc manual says proxy authentication is only supported for HTTP CONNECT proxies and describes a user name option but no password option, so it does not fit a SOCKS5 proxy with a login. The Ncat tool from the Nmap project has --proxy-type socks5 and --proxy-auth USERNAME:PASSWORD for exactly this. Install Ncat first (it comes with Nmap). The example below is the ssh_config form; the second command passes the same ProxyCommand for one run through GIT_SSH_COMMAND, which the Git documentation says is run by the shell.

The Ncat page does not show it inside a ProxyCommand, so test it with the check below. Also remember that some proxies only allow web ports and refuse a connection to port 22; if the connection closes at once, switch the remote to https:// instead.

• Sources:
• OpenBSD manual: ssh_config (ProxyCommand, ProxyJump)
• OpenBSD manual: nc
• Nmap Ncat guide: proxies
• Git docs: git (environment variables GIT_TRACE_CURL, GIT_SSH_COMMAND)

SSH remotes: ssh_config example

# ~/.ssh/config
Host github.com
  ProxyCommand ncat --proxy HOST:PORT --proxy-type socks5 --proxy-auth USERNAME:PASSWORD %h %p

Replace HOST, PORT, USERNAME and PASSWORD with the values from My assets.

SSH remotes: one run with GIT_SSH_COMMAND

GIT_SSH_COMMAND='ssh -o "ProxyCommand=ncat --proxy HOST:PORT --proxy-type socks5 --proxy-auth USERNAME:PASSWORD %h %p"' git ls-remote [email protected]:git/git.git HEAD

Replace HOST, PORT, USERNAME and PASSWORD with the values from My assets.

How to check that Git uses the proxy

1. Print what is set

   Run git config --show-origin --get-all http.proxy. It shows the value and the file it comes from, so you can find a forgotten setting.

2. Run a small command with the trace on

   git ls-remote asks the server for its list of branches and downloads no files. With GIT_TRACE_CURL=1 the first lines show which host and port Git connects to: it should be your proxy, not the Git server.

3. Check the exit address with curl

   The second command in the example below shows the IP, country and network that websites see through the same proxy. The guide on how to check your proxy's IP, country and ISP explains the fields.

   • how to check your proxy's IP, country and ISP

4. Then try a real clone

   Clone a small repository you can read, with the proxy set. If it works and the trace points to the proxy host, you are done.

How to check that Git uses the proxy: example

GIT_TRACE_CURL=1 git ls-remote https://github.com/git/git.git HEAD
curl -x http://USERNAME:PASSWORD@HOST:PORT https://ipinfo.io/json

Replace HOST, PORT, USERNAME and PASSWORD with the values from My assets.

Common errors

• Proxy CONNECT aborted, or 407 Proxy Authentication Required. The proxy rejected the username or password. Copy them again and check the percent-encoding.

• Could not resolve proxy, or Failed to connect. Wrong HOST or PORT, or the lease has ended. Test the same address with the curl command above.

• The proxy works for curl but Git hangs. Check git config --show-origin --get-all http.proxy for a leftover value.

• Cloning over ssh ignores the proxy. This is expected: set ProxyCommand as shown, or use the https:// address.

• Connection closed at once over ssh. The proxy may not allow port 22; use an https:// remote.

• authentication required guide
• connection failed guide

• Sources:
• Git docs: git-config (http.proxy, http.<url>.*, remote.<name>.proxy)

How to do it with Proxy302

Every command here needs only the host, port, username and password of a Proxy302 proxy. Rotating residential traffic is billed per GB and the exit country is set when you generate the proxy; HTTP is on port 2222 and SOCKS5 on port 3333 of proxy.proxy302.com. A static ISP IP stays fixed for the whole lease and does not rotate, which suits a tool that you want to always leave from the same address. HTTP or SOCKS5 is chosen when you buy, and one IP carries one protocol.

• rotating residential page
• SOCKS5 proxies page

• Sources:
• Proxy302 product facts and price list

How to do it with Proxy302: steps

1. Step 1

   Open the rotating residential page, choose the line, keep Protocol on HTTP (or choose SOCKS5), then click Review cost and generate.

2. Step 2

   Open My assets (the console page that holds everything you bought) and copy HOST, PORT, USERNAME and PASSWORD. The Connect page shows a ready example with your own endpoint.

3. Step 3

   Put the values into the commands above.

4. Step 4

   Confirm the exit with https://ipinfo.io/json through the proxy.

   • how to check your proxy's IP, country and ISP

5. Step 5

   From mainland China, start the helper tool from the Connect page first and keep it open while you use the proxy.

   • Helper tool guide

Prices and limits

The Budget line costs US$1.50 per GB, US$1.35 per GB in a 100 GB package and US$1.20 per GB at 300 GB. A static ISP IP costs US$0.50 for one day and US$7.99 for 30 days. There is no free trial, and the smallest purchase is 1 GB or one IP for one day. Which exit locations are available changes daily.

• Sources:
• Proxy302 product facts and price list

FAQ

Read next

curl proxy setup

Use an HTTP or SOCKS5 proxy with curl: -x, credentials, socks5h, environment variables, .curlrc and an exit check.

SOCKS5 proxies

SOCKS5 on all three lines: rotating residential from US$1.50/GB, static ISP and datacenter IPs per IP and term. Port 3333 with username and password, and the errors you see when a setting is wrong.

Check a proxy's IP, country and ISP

Check the exit IP, country and ISP your proxy really gives you in 30 seconds — and why IP databases disagree on the city. With our own test of three lookup services.

407 Proxy Authentication Required

HTTP 407 Proxy Authentication Required comes from the proxy server, not from the website you are trying to reach.