APITesterThe command
curl -x http://proxy.example.com:8080 https://httpbin.org/ipWhat the flags do
| Flag | What it does |
|---|---|
-x [scheme://]host:port | Use this proxy. Long form: --proxy. Default scheme is http. |
-U user:password | Credentials for the proxy itself. Long form: --proxy-user. |
--noproxy list | Comma-separated hosts to reach directly. "*" disables proxies. |
-x socks5h://host:port | SOCKS5, with hostnames resolved by the proxy. |
HTTP proxies and HTTPS targets
Through an HTTP proxy, a plain http:// request is handed to the proxy to perform. For an https:// target curl instead asks the proxy to open a tunnel with CONNECT and then does TLS end to end inside it, so the proxy sees the destination host and nothing else. Verification of the target's certificate works exactly as it does without a proxy.
Proxy credentials are separate from site credentials: -U authenticates you to the proxy, -u to the destination.
curl -x http://proxy.example.com:8080 -U alice:pw https://httpbin.org/ip
curl -x http://proxy.example.com:8080 -U alice:pw -u apiuser:apipw https://api.example.com/SOCKS proxies
SOCKS works at the connection level and carries any protocol. The scheme matters: socks5:// resolves the hostname on your machine and sends the proxy an IP address, while socks5h:// sends the hostname and lets the proxy resolve it. Use the h form whenever local DNS should not see the lookup, or cannot answer it, as with an SSH tunnel into a private network.
ssh -D 1080 -N bastion.example.com & # a local SOCKS proxy over SSH
curl -x socks5h://localhost:1080 https://internal.example.com/Environment variables
Curl reads https_proxy, HTTPS_PROXY, all_proxy, ALL_PROXY and no_proxy. The one exception is http_proxy, which is honoured in lower case only, a deliberate guard against a CGI security problem. A proxy set in the environment applies to every curl command in that shell, which is the usual explanation when a request behaves differently on a server than on your laptop.
export https_proxy=http://proxy.example.com:8080
export no_proxy=localhost,127.0.0.1,.internal.example.com
curl https://httpbin.org/ip # via the proxy
curl --noproxy "*" https://httpbin.org/ip # direct, ignoring the environmentCommon mistakes
407 Proxy Authentication Requiredcomes from the proxy, not the site. It wants-U.- The default proxy port is 1080 when you leave it out, not 8080 or 3128.
- Corporate proxies that inspect TLS present their own certificate. Trust the company CA with
--cacert; do not reach for-k.
Related curl examples
Curl HTTPS Request Example
An https:// URL is all curl needs to use TLS, and it verifies the server's certificate by default.
Curl Timeout Example
By default curl puts no limit on how long a transfer may take, so one silent server can hang a script indefinitely.
Curl Ignore Certificate Checks Example
-k tells curl to proceed even though it cannot verify who it is talking to.
Curl Flags Example
Curl has well over two hundred options.
DNS Lookup
Compare what public resolvers return with what your proxy or network resolves.
All Curl Examples
49 worked examples, grouped by what you are trying to do.
More under Network behaviour
References
- curl man page: -x — Sending a request through a proxy.
- MDN: Proxy servers and tunneling — Forward proxies, reverse proxies and the CONNECT method.
These links leave api-tester.com, which is independent of the projects they point to.
FAQ
How do I use a proxy with curl?
Pass -x followed by the proxy address, for example curl -x http://proxy.example.com:8080 URL. Add -U user:password if the proxy requires authentication.
How do I use a SOCKS5 proxy with curl?
Use -x socks5h://host:port to send hostnames to the proxy for resolution, or socks5://host:port to resolve them locally.
How do I make curl ignore the proxy environment variables?
Add --noproxy "*" to the command. Curl then connects directly regardless of http_proxy, https_proxy or all_proxy.