As a developer, you do a lot of debugging, testing of geo-restricted content, and routing traffic through a proxy server for privacy or compliance. Using cURL can make it much easier to work from behind a proxy.
With just a few flags, you can tell cURL to send traffic through HTTP or SOCKS proxies with or without authentication. Since cURL supports everything from simple IP:port pairs to full proxy credentials, it’s a great option for developers.
In this guide, we’ll walk through the different ways to use cURL with proxy servers, including:
- How to use HTTP and SOCKS5 proxies
- How to pass authentication credentials
- How to verify that your requests are actually being routed through the proxy
Using cURL you can use both HTTP and SOCKS proxies with just a few flags.
How to Use an HTTP Proxy with cURL
cURL HTTP Proxy without Authentication
Using an HTTP proxy with cURL is straightforward. You just need to pass the proxy address using the -x or --proxy flag.
Basic Syntax:
curl -x http://proxyhost:port https://example.comExample:
curl -x http://192.168.1.100:8080 https://httpbin.org/ipIn the example above:
-xtells cURL to use a proxy- http://192.168.1.100:8080 is the proxy server
- The request to https://httpbin.org/ip will go through the proxy
CURL HTTP Proxy with Authentication
If your proxy requires a username and password, include them in the proxy URL:
curl -x http://username:password@proxyhost:port https://example.comExample:
curl -x http://user123:[email protected]:8080 https://httpbin.org/ipWhen to use:
- Your network requires traffic to go through an internal proxy
- You want to test how your API behaves from a different location/IP
- You’re debugging traffic that passes through CDN or proxy layers
Security tip: Avoid pasting proxy credentials directly into the command line. You can use --proxy-user instead:
curl --proxy http://proxyhost:port --proxy-user user:pass https://example.com
How to Use a SOCKS Proxy with cURL?
SOCKS proxies operate at a lower level than HTTP proxies, making them perfect for routing any kind of traffic, not just HTTP. This is especially handy when testing applications, accessing geo-restricted content, or tunneling traffic securely through another server.
cURL SOCKS Proxy without Authentication
You can use --socks5, --socks4, or socks5-hostname depending on the version of SOCKS and DNS resolution behavior.
curl --socks5 socks_host:port https://example.comExample:
curl --socks5 127.0.0.1:9050 https://httpbin.org/ipThis tells cURL to route traffic through the SOCKS5 proxy running locally on port 9050 (which is the default port for Tor).
cURL SOCKS Proxy with Authentication
If the SOCKS proxy requires a username and a password:
curl --socks5-user user --socks5-password pass --socks5 socks_host:port https://example.comExample:
curl --socks5-user myuser --socks5-password mypass --socks5 192.168.0.5:1080 https://httpbin.org/ip
SOCKS vs HTTP Proxy with cURL
| Feature | HTTP Proxy | SOCKS Proxy |
|---|---|---|
| Protocol-specific | Yes (HTTP/S only) | No (can proxy any protocol) |
| DNS resolution control | Limited | More flexible (hostname vs IP) |
| Use cases | APIs, web requests | Full tunneling, Tor, dev/test |
| Supported in cURL | Yes | Yes (with --socks5, etc.) |
--socks5-hostname vs --socks5
- –socks5: DNS resolution happens on the client side.
- –socks5-hostname: DNS resolution happens on the proxy side.
Use --socks5-hostname when:
- You want to hide DNS queries from your ISP.
- You’re using a remote proxy (e.g., Tor node, VPN, or remote gateway).
curl --socks5-hostname 127.0.0.1:9050 https://example.com
How to Use an HTTPS Proxy with cURL
While HTTP proxies are more common, HTTPS proxies offer an added layer of security by encrypting the traffic between your machine and the proxy server. This is useful when working in environments where privacy and confidentiality are critical such as corporate networks, VPN-like setups, or secure data pipelines.
cURL HTTPS Proxy without Authentication
Basic Syntax for HTTPS Proxy:
To use an HTTPS proxy with cURL, you can use the --proxy flag and specify the scheme as https://
curl --proxy https://proxy_host:proxy_port https://example.comExample:
curl --proxy https://myproxy.example.com:443 https://httpbin.org/ipThis commands routes your requests to httpbin.org through an HTTPS proxy
Using HTTPS Proxy with Authentication
If your HTTPS proxy requires a username and password, you can include them inline or use --proxy-user.
Inline in the URL (basic auth):
curl --proxy https://username:password@proxy_host:port https://example.comOr with --proxy-user:
curl --proxy https://proxy_host:port --proxy-user username:password https://example.comExample:
curl --proxy https://proxy.mycompany.com:443 --proxy-user admin:secure123 https://example.comAvoid hardcoding credentials in scripts; use environments, variables, or prompt users securely.
Handling HTTPS Proxy with Self-Signed Certificates
If your HTTPS proxy uses a self-signed certificate (common in internal networks), you may run into certificate errors. You can skip SSL verification only if you trust the proxy:
curl --proxy https://proxy.example.com:443 --proxy-insecure https://example.comAlternatively, you can add a custom CA bundle with:
curl --proxy-cacert my-ca.crt --proxy https://proxy.example.com:443 https://example.comVerbose Output (Optional for Debugging)
Want to see how the connection flows through the proxy?
curl -v --proxy https://proxy.example.com:443 https://example.comThis will show you the full TLS handshake, proxy connection status, and headers exchanged.
Summary Table
| Feature | Usage Example |
|---|---|
| HTTPS Proxy (no auth) | curl --proxy https://host:port https://site.com |
| HTTPS Proxy (with auth) | --proxy-user user:pass or inline URL |
| Self-signed cert bypass | --proxy-insecure |
| Provide custom CA for proxy | --proxy-cacert file.crt |
| Debug with verbose | -v |
How to Use cURL with Proxy Authentication
Many proxy servers require authentication for access, especially in corporate networks or paid proxy services. Fortunately, cURL makes it easy to handle proxy auth.
Basic Proxy Authentication with --proxy-user:
The most common way is to use the --proxy-user option:
curl --proxy http://proxy.example.com:8080 --proxy-user username:password https://example.comThis will include a Proxy-Authorization header with your request.
Example:
curl --proxy http://123.45.67.89:8080 --proxy-user myuser:mypass https://httpbin.org/ipYou’ll get a response from httpbin.org, routed through the proxy with credentials included
Supported Authentication Methods:
By default, cURL tries Basic authentication, but if the proxy requires NTLM, Digest, or Negotiate/Kerberos, cURL supports those too:
- Use
--proxy-ntlmfor NTLM - Use
--proxy-digestfor Digest auth - Use
--proxy-negotiatefor Kerberos or Negotiate
Example:
curl --proxy http://proxy.company.local:8080 --proxy-user domain\\user:pass --proxy-ntlm https://example.comKeep in mind that double backslashes \\ are required in Windows domain-style logins.
Conclusion
Now that we’ve covered a variety of ways to use cURL with proxy servers, we hope you can see how useful this setup is in different scenarios. Using proxy with cURL can make a developer’s life much easier, especially when working with APIs, managing large scale requests, or testing behavior across multiple regions.
Key takeaways:
- Use
--proxyto specify a proxy server. - Use
--proxy-userto authenticate with username and password. - Use
--proxy-ntlm,--proxy-digest, or--proxy-negotiatefor advanced authentication methods. - Use HTTPS proxies for secure communication.
- Combine with flags like
-x,-v, or-Lfor full control.
Setting the right authentication method is super important, choosing the right proxy protocol, and combining flags like -L (follow redirects) or -v (verbose output) can make your proxy setup smoother and more powerful.
