Skip to content

cURL Proxy Example: How to Use and Test a Proxy with cURL

By . Published . Updated

cURL Proxy Example (TL;DR)

The fastest way to test a proxy with cURL is a single -x command:

curl -x http://username:password@proxy.example.com:8080 https://ifconfig.me

If the response prints the proxy's IP instead of yours, the proxy is working. The rest of this guide expands on this example with HTTP, HTTPS, and SOCKS5 variants, authentication, error handling, and a script for batch testing.

Why Test a Proxy with cURL?

Testing a proxy is an essential step to ensure it functions correctly before deploying it for critical tasks like web scraping, browsing, or API calls. cURL is the simplest tool for the job - it's pre-installed on most systems and gives you direct, reproducible output you can paste into a bug report or a teammate's chat.

What You'll Need

  • A proxy: HTTP, HTTPS, or SOCKS5. For this guide we'll use a sample HTTP proxy at proxy.example.com:8080 with the username myuser and password mypass.
  • cURL installed: check with curl --version. macOS ships with it, and so do current versions of Windows 10 and 11 (run it from Command Prompt or PowerShell). On Debian or Ubuntu, install it with sudo apt-get install curl; on Fedora or RHEL, sudo dnf install curl. Anything else, grab a build from curl.se.

Basic cURL Command Structure

The general syntax for using cURL with a proxy is:

curl -x [proxy_url] [target_url]

Here:

  • -x (long form --proxy) specifies the proxy.
  • [proxy_url] is the proxy's address and port, optionally with a scheme and credentials.
  • [target_url] is the URL you want to access through the proxy.

The full form of the proxy URL is:

curl -x [protocol://][username:password@]proxyhost:port [URL]
  • protocol: http, https, socks5, or socks5h. If you leave it off, cURL assumes HTTP.
  • username:password@: your proxy credentials, if the proxy requires them.
  • proxyhost:port: the proxy server's hostname or IP and port.

Example

Suppose you want to test if a proxy works with https://www.example.com. The command would be:

curl -x http://proxy.example.com:8080 https://www.example.com

If the proxy is working, you'll see the response from the target URL. If not, you'll encounter an error message.

Adding Authentication

Some proxies require a username and password for authentication. Use the -U flag to include credentials:

curl -x http://proxy.example.com:8080 -U username:password https://www.example.com

Replace username and password with your actual credentials. -U is short for --proxy-user. You can also put the credentials straight into the proxy URL, which is handier in scripts:

curl -x http://myuser:mypass@proxy.example.com:8080 https://www.example.com

If your password contains special characters such as @, : or #, URL-encode them (@ becomes %40) or use -U instead, where they don't need escaping.

Testing Different Proxy Types

HTTP/HTTPS Proxy: Use the http or https scheme in the proxy URL:

curl -x http://proxy.example.com:8080 https://www.example.com

SOCKS Proxy: Use the socks4 or socks5 scheme for SOCKS proxies:

curl -x socks5://proxy.example.com:1080 https://www.example.com

Use socks5h:// instead of socks5:// if you want the proxy to resolve DNS for you. With plain socks5://, cURL looks up the hostname locally first, which leaks the domain you're visiting to your own resolver and can return a different IP than the proxy would see.

Setting a Proxy with Environment Variables

If you use the same proxy all day, set it once as an environment variable and cURL will pick it up on every request without -x.

Linux/macOS:

export http_proxy="http://myuser:mypass@proxy.example.com:8080"
export https_proxy="http://myuser:mypass@proxy.example.com:8080"
export no_proxy="localhost,127.0.0.1"

Windows (Command Prompt):

set http_proxy=http://myuser:mypass@proxy.example.com:8080
set https_proxy=http://myuser:mypass@proxy.example.com:8080

no_proxy lists hosts that should skip the proxy. To bypass the proxy for a single command without unsetting anything, add --noproxy "*". Note that https_proxy is the proxy used for HTTPS URLs; the proxy itself can still be a plain http:// endpoint, which is the normal setup.

Checking the Proxy's IP Address

To confirm the proxy is routing your request, you can check your IP address using services like https://ifconfig.me or https://ipinfo.io. For example:

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

The output should display the proxy's IP address, not your own.

Testing Proxy Speed

To measure the proxy's speed, you can use the -w flag to output timing details:

curl -x http://proxy.example.com:8080 -o /dev/null -s -w 'Time: %{time_total}\n' https://www.example.com

This command will:

  • Suppress the response body (-o /dev/null).
  • Print only the total time taken for the request (-w 'Time: %{time_total}\n').

Handling Errors

If the proxy isn't working, cURL might display errors like:

  • Failed to connect: Indicates the proxy is unreachable.
  • 407 Proxy Authentication Required: Suggests authentication credentials are missing or incorrect.
  • Timeout: Could mean the proxy is slow or overloaded.

Check the proxy's configuration and ensure it's active and properly set up.

Automating Proxy Testing

If you have multiple proxies to test, you can automate the process with a simple shell script:

#!/bin/bash

proxies=(
  "http://proxy1.example.com:8080"
  "http://proxy2.example.com:8080"
  "http://proxy3.example.com:8080"
)

target_url="https://www.example.com"

for proxy in "${proxies[@]}"; do
  echo "Testing proxy: $proxy"
  curl -x "$proxy" -o /dev/null -s -w "Time: %{time_total}\n" "$target_url"
  echo "---"
done

Save the script as test_proxies.sh, make it executable (chmod +x test_proxies.sh), and run it. This will test each proxy in the list and display the time taken for each.

Conclusion

These cURL proxy examples cover everything you need to verify connectivity, confirm the exit IP, measure latency, and authenticate against an upstream proxy. Drop them into your shell, swap in your own credentials, and you have a reliable way to validate any proxy before it touches production traffic.

If a test fails with a 407, our guide to fixing proxy 407 authentication errors walks through the usual causes, and cURL basic auth covers authenticating against the target site itself. And if you need reliable, authenticated proxies that pass these tests on the first try, take a look at our static ISP proxy plans or static residential proxies: dedicated US IPs with unlimited bandwidth, HTTP, HTTPS and SOCKS5 on the same credentials.