How to use a proxy with curl

Setup guide · Last revised Oct 20, 2026

The one command

curl -x "http://USERNAME:[email protected]:8000" https://api.ipify.org

The output is the address the site saw:

203.0.113.24

Run the same command without -x. If both print the same address, your requests are not going through the proxy. The host, port and login come from your provider’s dashboard; many providers give one gateway address and change the exit IP behind it.

Keep the password out of the address

If the password contains @, : or #, the address breaks at that character. Either encode it (curl decodes the login in a proxy address, so “you can pass in special characters such as @ by using %40 or pass in a colon with %3a”, curl man page), or pass it on its own with -U:

curl -x http://proxy.example.com:8000 -U "USERNAME:PASSWORD" https://api.ipify.org

To keep it out of your shell history and scripts, set it once in an environment variable that curl reads:

export https_proxy="http://USERNAME:[email protected]:8000"
curl https://api.ipify.org

A -x on the command line “overrides existing environment variables that set the proxy to use” (curl man page). --noproxy "*" skips the proxy for one command.

Make the proxy curl’s default

To send every curl command through the proxy without typing it, put it in curl’s own settings file, ~/.curlrc on Linux and macOS, and make the file readable only by you, since the login is in it in plain text:

echo 'proxy = "http://USERNAME:[email protected]:8000"' >> ~/.curlrc
chmod 600 ~/.curlrc

From then on a plain curl goes through the proxy. To skip the file for one command, make -q the first option: “If used as the first parameter on the command line, the curlrc config file is not read or used” (curl man page). Our run printed both:

curl -s -o /dev/null -w "proxy %{http_connect} site %{http_code}\n" https://api.ipify.org
curl -q -s -o /dev/null -w "proxy %{http_connect} site %{http_code}\n" https://api.ipify.org

proxy 200 site 200
proxy 000 site 200

proxy 000 means no proxy was used. The file applies to every curl you run under that user, including scripts and installers that call curl, so on a plan billed by the GB they spend your traffic too. On Windows curl looks for the same file as %USERPROFILE%\.curlrc (curl man page).

SOCKS5

curl -x "socks5h://USERNAME:[email protected]:1080" https://api.ipify.org

Use socks5h://, not socks5://: with the h, the proxy looks up the site’s name, so your own network never sees which site you asked for (DNS leaks through a proxy). Our test SOCKS5 server logged the difference: with socks5h:// it received the name api.ipify.org and looked it up itself; with socks5:// it received only an IP address that curl had already looked up on our side. A wrong SOCKS5 password prints curl: (97) User was rejected by the SOCKS5 server (1 1). curl assumes port 1080 for a SOCKS proxy when you give none. Which protocol to buy: HTTP vs SOCKS5.

Tell a proxy error from a site error

curl can print the proxy’s answer and the site’s answer in one line. %{http_connect} is “the numerical code that was found in the last response (from a proxy) to a curl CONNECT request”:

curl -s -o /dev/null -x "$https_proxy" \
  -w "proxy %{http_connect} site %{http_code}\n" https://api.ipify.org

What our test printed for each case:

This works for https:// addresses, where curl opens a tunnel through the proxy. For a plain http:// address the proxy fetches the page itself, so http_connect stays 000.

When curl cannot reach the proxy at all

curl: (7) Failed to connect to proxy.example.com port 8000 after 0 ms: Couldn't connect to server
curl: (5) Could not resolve proxy: proxy.example.com
curl: (28) Operation timed out after 3002 milliseconds with 0 bytes received

Error 7 means nothing answered on that port: check the port, and whether your network blocks outgoing connections to it. Error 5 means the proxy’s host name is wrong. Error 28 is a timeout; --max-time 30 sets how long curl waits.

Next

How to test a proxy checks the location, the rotation and the speed with the same commands. The same setup in a script: Python Requests.