curl With Proxy: How to Use a curl Proxy (HTTP, SOCKS5, Auth, Env Vars)

Developer guide · Last reviewed 1 October 2026 · 13 min read

To use curl with proxy servers, add -x (or --proxy) followed by the proxy’s scheme, host and port, and put the username and password either in that string or in -U. This guide covers every curl proxy option you are likely to need: HTTP, HTTPS, SOCKS5 and socks5h proxies, proxy authentication and URL-encoding, the http_proxy, https_proxy, ALL_PROXY and NO_PROXY variables, --noproxy, a permanent proxy in .curlrc, how to check your exit IP, sticky and rotating sessions on a rotating residential proxy, and how to read the errors. Every flag here was checked against the curl manual and the libcurl documentation.

curl with proxy: the basic -x command

curl is the command-line tool for transferring data with URLs, and it comes with macOS and with Windows 10 and 11, and is a standard package on every Linux distribution. To send a request through a proxy you only need one option: -x, or its long form --proxy. Both do exactly the same thing. The value is a proxy string in the form [scheme://][user:password@]host[:port], and the URL you want to fetch comes after it.

# no authentication
curl -x http://proxy.example.com:8080 https://ifconfig.me

# long form, with a username and password in the proxy string
curl --proxy "http://USERNAME:PASSWORD@proxy.example.com:8080" https://ifconfig.me

Each part of the proxy string has a job:

Write the port every time. The libcurl documentation tells you not to assume any particular port is widely used for proxies, and to specify it. If you leave it out, curl falls back to a built-in default that is very unlikely to be the port your provider uses, and the connection fails or times out.

Put the whole proxy string in double quotes. Usernames and passwords can contain characters such as &, $ or ! that bash, zsh or PowerShell would otherwise interpret before curl sees them. On Windows PowerShell 5.1, type curl.exe rather than curl: there, curl is an alias for PowerShell’s own Invoke-WebRequest, which doesn’t understand curl’s options. The curl project documents this alias and the curl.exe workaround.

If you give -x more than once, the last one wins. A proxy set on the command line also overrides any proxy set in the environment variables covered below.

curl proxy schemes: HTTP, HTTPS, SOCKS5 and socks5h

The scheme at the start of the proxy string tells curl what kind of proxy it is talking to. The curl manual lists six prefixes. An unknown or unsupported scheme makes curl stop with an error rather than guess.

HTTP proxy with an HTTPS site

When you fetch an https:// URL through an http:// proxy, curl doesn’t hand the request to the proxy. It sends CONNECT example.com:443, the proxy opens a raw TCP tunnel to the site, and curl negotiates TLS with the site through that tunnel. The proxy relays encrypted bytes it can’t read or change. When you fetch a plain http:// URL, curl sends the whole request to the proxy, which reads it and forwards it. To force a tunnel for plain HTTP too, add -p (--proxytunnel). The proxy must allow CONNECT to the port you want, and many proxies only allow 443 and a few others.

HTTPS proxy

An https:// proxy prefix encrypts the hop between curl and the proxy, so someone on your local network can’t read the traffic, including the proxy credentials. The curl manual lists HTTPS proxy support for the OpenSSL, GnuTLS, mbedTLS, Rustls, Schannel and wolfSSL TLS backends. Use --proxy-cacert if the proxy’s certificate is signed by a private CA. Only use an https:// prefix when your provider gives you an HTTPS proxy endpoint; pointing it at a plain HTTP proxy port fails the TLS handshake.

socks5 vs socks5h: where DNS happens

This is the difference people miss. With socks5://, curl looks up the website’s hostname on your own machine and sends the proxy an IP address. With socks5h://, curl sends the hostname and the proxy resolves it. The curl project’s own table puts it simply: SOCKS5 means curl resolves the name, SOCKS5h means the proxy does.

Use socks5h:// with a proxy in another country. Your local resolver never sees which sites you visit, and you get the addresses the proxy’s side of the network returns, which matters for sites that answer DNS differently by region. It also works when your machine can’t resolve the target at all. SOCKS5 carries the username and password with its own sub-negotiation (RFC 1929), and curl sends it whenever you give credentials.

# curl resolves example.com itself, then asks the proxy for that IP
curl -x "socks5://USERNAME:PASSWORD@proxy.example.com:1080" https://example.com

# the proxy resolves example.com (DNS goes through the proxy)
curl -x "socks5h://USERNAME:PASSWORD@proxy.example.com:1080" https://example.com

# equivalent long options
curl --socks5-hostname proxy.example.com:1080 -U "USERNAME:PASSWORD" https://example.com

Our SOCKS proxy guide explains how SOCKS5 differs from HTTP proxies in more depth. For most HTTP and HTTPS work, an HTTP proxy and a SOCKS5 proxy give the same result; pick the one your tool or network handles best.

Proxy authentication: -U and credentials in the URL

Most commercial proxies need a username and password. curl accepts them in two places, and the result on the wire is the same: a Proxy-Authorization header for HTTP proxies, or the SOCKS5 username and password exchange.

# 1. in the proxy URL
curl -x "http://USERNAME:PASSWORD@proxy.example.com:8080" https://example.com

# 2. with -U / --proxy-user
curl -x http://proxy.example.com:8080 -U "USERNAME:PASSWORD" https://example.com

Don’t confuse -U with lowercase -u. -U (--proxy-user) logs in to the proxy; -u (--user) logs in to the website. Mixing them up is one of the most common reasons for a 407.

URL-encoding special characters

curl URL-decodes the username and password in the proxy string, and libcurl’s documentation for proxy credentials says the same of the value you pass with -U. In our test with curl 8.21, both forms decoded %40 to @. So if your password contains a character that means something in a URL, replace it with its percent-encoded form:

A password of p@ss:w#rd becomes p%40ss%3Aw%23rd. When a login that works in a browser fails in curl with 407, an unencoded character in the password is the first thing to check.

Authentication schemes

curl uses HTTP Basic authentication with proxies by default, which is what nearly every commercial proxy expects. If a corporate proxy wants something else, its 407 response names the scheme, and you can ask for it with --proxy-digest or --proxy-ntlm, or let curl pick with --proxy-anyauth at the cost of an extra round trip.

Keep credentials off the command line

The curl manual warns that a password given with -U can briefly show up in process listings, even though curl hides it where the system allows, and recommends reading sensitive data from a file instead. Put the proxy line in a config file that only you can read and load it with -K, as shown in the .curlrc section below. Also keep secrets out of scripts you commit to git, and remember that your shell history records every command you type.

Proxy environment variables

Instead of adding -x to every command, you can set the proxy once in environment variables. curl reads them before every run, and the manual says setting a proxy this way has the same effect as --proxy. Each variable takes the same proxy string as -x, credentials included.

Two details catch people out. First, curl ignores an upper-case HTTP_PROXY. The curl project explains why: web servers running CGI scripts turn an incoming Proxy: request header into an HTTP_PROXY variable, so honouring it would let any visitor redirect a script’s traffic. Every other variable works in either case, and the lower-case one wins if both are set. Second, https_proxy names the proxy for HTTPS sites. Its value can, and usually does, start with http://, because that is how curl talks to the proxy.

# Linux and macOS (bash, zsh)
export http_proxy="http://USERNAME:PASSWORD@proxy.example.com:8080"
export https_proxy="$http_proxy"
export no_proxy="localhost,127.0.0.1,.internal.example"
curl https://ifconfig.me
unset http_proxy https_proxy no_proxy      # back to direct

# Windows PowerShell
$env:https_proxy = "http://USERNAME:PASSWORD@proxy.example.com:8080"
curl.exe https://ifconfig.me
Remove-Item Env:https_proxy

# Windows Command Prompt (quotes around the whole assignment, not the value)
set "https_proxy=http://USERNAME:PASSWORD@proxy.example.com:8080"
curl https://ifconfig.me

Environment variables work on every system curl runs on, Windows included; Windows just doesn’t distinguish upper- and lower-case names. They also reach other programs: many command-line tools and language libraries read the same variables, so an export in your shell may send more than curl through the proxy. Our wget proxy guide covers wget’s own settings.

Skipping the proxy: –noproxy and NO_PROXY

Once a proxy is set in the environment or in .curlrc, you’ll sometimes want a request to go direct. --noproxy takes a comma-separated list of hosts that should skip the proxy. The only wildcard is a single *, which matches every host and switches the proxy off for that command.

# go direct for this one request, whatever proxy is configured
curl --noproxy "*" https://example.com

# skip the proxy for local and internal hosts only
curl --noproxy "localhost,127.0.0.1,internal.example.com" https://internal.example.com/health

# an empty proxy string also overrides a proxy set in the environment
curl -x "" https://example.com

Names are matched as a domain that contains the host, or the host itself: example.com matches example.com and www.example.com, but not www.notexample.com. Since curl 7.86.0 you can also exclude a network in CIDR notation, such as 192.168.0.0/16. --noproxy overrides NO_PROXY from the environment, and --noproxy "" clears an environment exclusion list for one command.

Note the order of precedence. A host listed in NO_PROXY skips the proxy even when you name one with -x on the command line, so if a single host refuses to use your proxy, check that variable first.

A permanent curl proxy in .curlrc

curl reads a default config file before every run, unless you tell it not to. Any long option can go in it, one per line, written without the leading dashes. To make every curl command use your proxy, put a proxy line in it.

# ~/.curlrc  (Windows: %USERPROFILE%\.curlrc or %APPDATA%\.curlrc)
proxy = "http://USERNAME:PASSWORD@proxy.example.com:8080"
noproxy = "localhost,127.0.0.1"
connect-timeout = 15
max-time = 60

Options and values can be separated by whitespace, a colon or an equals sign. Quote any value that contains spaces or starts with : or =, and start comment lines with #. curl looks for the file in this order: $CURL_HOME/.curlrc, $XDG_CONFIG_HOME/curlrc, $HOME/.curlrc, and on Windows %USERPROFILE%\.curlrc and %APPDATA%\.curlrc, among others. On Windows it accepts .curlrc or _curlrc in each location and prefers .curlrc; older Windows builds only looked for _curlrc.

• Skip the file for one command: put -q (--disable) as the very first argument, curl -q https://example.com. Anywhere else on the line it has no effect.
• Override it for one command: a -x on the command line replaces the proxy from the file, because the last value wins.
• Keep several profiles: save proxy settings in separate files and pick one with -K, for example curl -K ~/proxy-us.conf https://example.com. This is also the safer way to keep credentials off the command line; make the file readable only by you (chmod 600).

A default proxy in .curlrc applies to everything, including scripts and tools that call curl on your behalf. If requests to local services suddenly fail, a forgotten .curlrc is a good suspect.

Testing the exit IP

The quickest check of any curl with proxy setup is to ask a service that echoes your IP address, once without the proxy and once with it. If the second answer is different and belongs to the expected country, the proxy works.

# your own IP
curl -s https://ifconfig.me ; echo

# the exit IP through the proxy
curl -s -x "http://USERNAME:PASSWORD@proxy.example.com:8080" https://ifconfig.me ; echo

# status codes and timing, handy in scripts (%{http_connect} is the proxy's CONNECT answer)
curl -s -o /dev/null -x "http://USERNAME:PASSWORD@proxy.example.com:8080" \
     -w "proxy=%{http_connect} site=%{http_code} time=%{time_total}s\n" https://ifconfig.me

The -w write-out option prints variables after the transfer. %{http_code} is the site’s response code, %{http_connect} is the code the proxy returned to curl’s CONNECT request (200 means the tunnel opened, 407 means it refused your credentials), and %{time_total} is the whole request time. On Windows, replace /dev/null with NUL, and use ^ instead of \ to continue a line in Command Prompt (a backtick in PowerShell).

Use -s to hide the progress meter in scripts, and add -S so errors still print. Don’t use -f (--fail) as your only check: the manual says it isn’t fail-safe, and responses involving authentication, 401 and 407, can slip through.

Sticky and rotating sessions with ProxyEmpire in curl

ProxyEmpire’s rotating residential and mobile proxies use one gateway: host v2.proxyempire.io, port 5000. HTTP and SOCKS5 both run on that host and port with the same username and password. Authentication is by username and password only, so there is no IP whitelist to set up, and curl works the same from a laptop, a server or a CI runner.

Open the Proxy Manager in the dashboard and use the Connection Builder. Pick residential or mobile, then set where the IP should come from: country, region or state, city, ZIP code, ISP (carrier on mobile), ASN and OS fingerprint, all included at no extra charge. Then choose how the IP behaves:

• Every request: a new IP on every request. Good for scraping and price checks spread over many IPs.
• Same IP: a sticky session. The IP stays with no fixed time limit, until you rotate it or the device behind it goes offline. Use it when a series of requests has to come from one address, such as a login followed by page views.
• Custom TTL: the IP changes on a timer you set, up to two hours.

ProxyEmpire’s Connection Builder: targeting, rotation and connection details

Your choices are built into the proxy username, so a different location or session is simply a different username with the same host, port and password. Copy the full proxy string from the Connection Builder rather than typing it; the example below uses the same shape as the sample on ProxyEmpire’s product pages, where country-us selects the United States and sid-123456 holds a session.

# HTTP proxy, US exit
curl -x "http://YOUR_USERNAME-country-us-sid-123456:YOUR_PASSWORD@v2.proxyempire.io:5000" https://ifconfig.me

# the same proxy over SOCKS5, DNS resolved by the proxy
curl -x "socks5h://YOUR_USERNAME-country-us-sid-123456:YOUR_PASSWORD@v2.proxyempire.io:5000" https://ifconfig.me

# sticky: repeat with the same session ID and the exit IP stays the same
for i in 1 2 3; do
  curl -s -x "http://YOUR_USERNAME-country-us-sid-123456:YOUR_PASSWORD@v2.proxyempire.io:5000" https://ifconfig.me; echo
done

# new session: change the session ID to get a different IP
curl -x "http://YOUR_USERNAME-country-us-sid-654321:YOUR_PASSWORD@v2.proxyempire.io:5000" https://ifconfig.me

curl has no rotation of its own: it sends each request through whatever proxy string you give it. Rotation happens at the gateway, so with Every request selected, a plain loop gets a new IP each time, and with a sticky session you rotate by changing the session ID. Our guide to sticky vs rotating proxies explains which to choose for which job, and rotating mobile proxies use the same gateway and username format when you need 4G or 5G carrier IPs.

Three limits worth knowing: only target ports 80 and 443 are open by default, so a request to an unusual port fails even when the proxy login is right; there is no UDP; and financial, government and other high-risk sites are blocked on all ProxyEmpire proxies. The ProxyEmpire endpoint examples here use http:// and socks5h://. Your connection to an https:// site is still encrypted end to end inside the tunnel.

Common curl proxy errors and how to fix them

When a curl with proxy command fails, curl reports an exit code and a one-line message. The codes below come from the curl manual; the messages are what curl 8.21 printed in our tests, and older versions word some of them slightly differently.

407 Proxy Authentication Required

A 407 always comes from the proxy, never from the website: RFC 9110 defines it as the proxy’s version of 401, sent when the client has to authenticate with the proxy. With curl the causes are almost always the same: no credentials at all (usually a missing -U or an environment variable that didn’t carry them), a typo, an unencoded @ or : in the password, or credentials sent to the website with -u instead of to the proxy. Our guide to 407 Proxy Authentication Required walks through the same error in C#, .NET and Python.

CONNECT tunnel failed

This message means curl asked an HTTP proxy to open a tunnel and the proxy said no. The number after “response” is the proxy’s status code: 407 for authentication, 403 when the proxy won’t tunnel to that destination or port, 502 or 503 when it couldn’t reach the target. Run the command again with -v to see the exact CONNECT line and the proxy’s reply.

Timeouts

By default curl waits a long time for a connection. Use --connect-timeout to limit the connection phase and -m (--max-time) to limit the whole transfer, both in seconds. With a residential or mobile proxy, the exit is a real device on a consumer connection, so an occasional slow request is normal: retry it, or move to a new session. Our overview of proxy error codes covers the codes other tools show for the same problems.

About -k

The old advice to “add -k” for certificate errors is risky. -k (--insecure) makes curl skip checking the site’s certificate, and the manual warns that it makes the transfer insecure. A trustworthy proxy using CONNECT never touches the site’s certificate, so a certificate error through a proxy usually points at a local problem, such as an outdated CA bundle or a corporate proxy that inspects TLS. Fix that instead. --proxy-insecure is the separate option that skips checking an HTTPS proxy’s own certificate; the same warning applies.

Reading curl -v output through a proxy

-v (--verbose) prints the conversation. Lines starting with * are curl’s own notes, > are headers curl sent and < are headers it received. Since curl 8.10, repeating the option (-vv) adds more detail. Here is a trimmed trace from our test of a proxy that rejects a request with no credentials:

$ curl -v -x http://192.0.2.10:5000 https://example.com
*   Trying 192.0.2.10:5000...                        <- connecting to the proxy, not the site
* Establishing HTTP proxy tunnel to example.com:443
> CONNECT example.com:443 HTTP/1.1                    <- curl asks for a tunnel
> Host: example.com:443
> User-Agent: curl/8.21.0
> Proxy-Connection: Keep-Alive
>                                                     <- no Proxy-Authorization header sent
< HTTP/1.1 407 Proxy Authentication Required         <- the proxy wants credentials
< Proxy-Authenticate: Basic realm="test"
* CONNECT tunnel failed, response 407
curl: (7) CONNECT tunnel failed, response 407

With working credentials the same trace shows * Proxy auth using Basic with user '...', a > Proxy-Authorization: Basic ... header, a 200 answer from the proxy and * CONNECT tunnel established, response 200, followed by the TLS handshake with the site. If the tunnel opens and the error comes later, the problem is between you and the website, not with the proxy login.

curl is also the fastest way to confirm a proxy works before you wire it into code. Once the command succeeds, the same host, port, username and password go straight into other tools; our guide to Python scraping with requests and residential proxies shows the equivalent setup in Python.

curl proxy FAQ

References

1. curl — curl.1 man page: –proxy, –proxy-user, –noproxy, –socks5-hostname, –config, ENVIRONMENT, exit codes. curl.se/docs/manpage.html
2. libcurl — CURLOPT_PROXY: proxy schemes, ports and environment variables. curl.se/libcurl/c/CURLOPT_PROXY.html
3. libcurl — CURLOPT_PROXYUSERPWD: proxy credentials are URL-decoded. curl.se/libcurl/c/CURLOPT_PROXYUSERPWD.html
4. libcurl — CURLOPT_NOPROXY: host matching rules. curl.se/libcurl/c/CURLOPT_NOPROXY.html
5. Everything curl — SOCKS proxy. everything.curl.dev/usingcurl/proxies/socks
6. Everything curl — Proxy environment variables. everything.curl.dev/usingcurl/proxies/env
7. Everything curl — HTTP proxy and CONNECT tunnelling. everything.curl.dev/usingcurl/proxies/http
8. curl — curl shipped by Microsoft (Windows and the PowerShell alias). curl.se/windows/microsoft.html
9. IETF — RFC 9110, “HTTP Semantics”: CONNECT (9.3.6) and 407 (15.5.8). rfc-editor.org/rfc/rfc9110
10. IETF — RFC 1929, “Username/Password Authentication for SOCKS V5”. rfc-editor.org/rfc/rfc1929