How to use a proxy with cURL

Your proxy details

After you buy a plan, open My proxies. Choose the Proxy Type (Rotating or Sticky), the Protocol (HTTP or SOCKS5) and a Format, then copy a line. The generator offers three formats:

In the examples on this page, replace USERNAME, PASSWORD, HOST and PORT with the values from your line. SOCKS5_PORT is the port the generator shows when you pick SOCKS5.

Residential lines are either rotating (a new IP on new connections) or sticky (one IP for the time you choose). Datacenter and ISP plans give you a list of dedicated IPs, one per line as IP:PORT:USERNAME:PASSWORD, and each line is one fixed IP.

To test a line, open https://ipinfo.io/json through it: it shows the exit IP and country. For HTTP lines you can also use the free proxy checker.

Basic authenticated proxy

curl -x "http://USERNAME:PASSWORD@HOST:PORT" https://ipinfo.io/json

curl -x "http://HOST:PORT" --proxy-user "USERNAME:PASSWORD" https://ipinfo.io/json

-x is short for --proxy, and -U is short for --proxy-user. In bash, wrap the values in single quotes instead if your password contains $ or !.

SOCKS5

curl -x "socks5h://USERNAME:PASSWORD@HOST:SOCKS5_PORT" https://ipinfo.io/json

socks5h:// sends the hostname to the proxy, so DNS is resolved at the exit. socks5:// resolves it on your machine first.

Use environment variables

export https_proxy="http://USERNAME:PASSWORD@HOST:PORT"
export http_proxy="http://USERNAME:PASSWORD@HOST:PORT"
curl https://ipinfo.io/json

cURL reads http_proxy only in lowercase. To make the proxy permanent, add a line such as proxy = "http://USERNAME:PASSWORD@HOST:PORT" to ~/.curlrc.

Rotating and sticky IPs

Each cURL run opens a new connection, so a rotating line prints a new IP each time, while a sticky line prints the same one until its duration ends. To make sticky lines, open the generator, set Proxy Type to Sticky, choose a Sticky Duration if your plan offers one, set how many lines you want in Sticky Amount, then copy or download them. Each line keeps its IP for the chosen time. The session part of a sticky username differs by plan, so always generate sticky lines instead of editing usernames by hand.

for i in 1 2 3; do
  curl -s -x "http://USERNAME:PASSWORD@HOST:PORT" https://ipinfo.io/ip
  echo
done

Target a country

On residential plans, add -country- and a two-letter country code to the end of the username, for example USERNAME-country-us or USERNAME-country-gb. To combine a country with a state, a city or a sticky session, build the line in the generator, which shows only the options your plan supports. Datacenter and ISP IPs have a fixed location that you choose when you buy them.

curl -x "http://USERNAME-country-us:PASSWORD@HOST:PORT" https://ipinfo.io/json

Debug a failing line

Add -v to see the conversation with the proxy. For an HTTPS site you’ll see a CONNECT request; a 200 reply means the tunnel is open, and anything else is the proxy’s reason for refusing, such as 407.

curl -v -x "http://USERNAME:PASSWORD@HOST:PORT" https://ipinfo.io/json

cURL on Windows

Windows 10 and 11 include curl. In Windows PowerShell, curl is an alias for Invoke-WebRequest, so type curl.exe to run the real cURL.

curl.exe -x "http://USERNAME:PASSWORD@HOST:PORT" https://ipinfo.io/json

Troubleshooting

• curl: (56) CONNECT tunnel failed, response 407

  The proxy rejected the username or password. Copy a fresh line and quote it.More on this error →

• curl: (56) CONNECT tunnel failed, response 502

  The proxy couldn’t reach the site through the exit IP. Retry, or widen your targeting.More on this error →

• curl: (7) Failed to connect to HOST port PORT

  Wrong host or port, or a firewall blocking the port.More on this error →

• curl: (35) … wrong version number

  Your proxy URL starts with https://. Use http://.More on this error →

• curl: (97) on a SOCKS5 line

  The SOCKS5 handshake failed. Check that you used the SOCKS5 port and the right credentials.

Seeing another error? Read proxy errors and how to fix them, or contact support.

Questions