cURL and proxies for beginners: the commands you need

In plain English: cURL is a small program you run by typing a command. You give it a web address and it prints whatever the site sends back. It comes already installed on most computers, including Macs, recent versions of Windows and most Linux systems, and it's a fast, simple way to try out a new proxy: one line tells you whether your details work before you set the proxy up anywhere else. Every part of each command is explained below, so you can follow along even if you've never opened a terminal.

Quick start in 3 steps

1. Open a terminal: Terminal on a Mac or Linux, Command Prompt on Windows.
2. Copy the first command in the next section and replace USER, PASS, HOST and PORT with your own details.
3. Press Enter. A reply showing the proxy's IP address, not yours, means the proxy works.

Your first request through the proxy

Copy your host, port, username and password from your dashboard (still choosing a plan? see our proxy types), then run:

curl -x "http://USER:PASS@HOST:PORT" https://api.ipify.org

Here's what each piece does:

• -x, or its long form --proxy, tells cURL to go through a proxy.
• The part in quotes is the proxy's address, with your username and password placed in front of the host.
• The last part, api.ipify.org, is a simple service that replies with the IP address it sees.

The http:// at the start of the proxy address describes how cURL talks to the proxy, not to the website. Secure https:// sites still work: cURL asks the proxy to open a tunnel (a method called CONNECT), and your connection to the site stays encrypted inside it.

Keeping the login separate

Rather not squeeze your password into the address? Pass it with -U instead (long form: --proxy-user):

curl -x "http://HOST:PORT" -U "USER:PASS" https://api.ipify.org

Both commands do the same job. If your account uses IP whitelisting, meaning your own IP address is approved in the dashboard, leave the login out altogether and point cURL at http://HOST:PORT.

Got SOCKS details?

SOCKS5 is an alternative to HTTP for connecting to a proxy. To use it, change the start of the address to socks5h:

curl -x "socks5h://USER:PASS@HOST:PORT" https://api.ipify.org

That h on the end matters. It lets the proxy look up website names itself (the DNS step), so those look-ups don't leak out over your own connection. Plain socks5 does the look-ups on your computer instead. If you'd rather use a flag, --socks5-hostname HOST:PORT behaves exactly like socks5h.

Set the proxy once for the whole window

Typing -x every time gets tiresome. An environment variable is a setting your terminal window remembers until you close it, and cURL looks for these automatically. On a Mac or Linux:

export http_proxy="http://USER:PASS@HOST:PORT"
export https_proxy="http://USER:PASS@HOST:PORT"
curl https://api.ipify.org

In Windows PowerShell, type curl.exe in full, as shown, because plain curl can start a different built-in PowerShell command:

$env:http_proxy = "http://USER:PASS@HOST:PORT"
$env:https_proxy = "http://USER:PASS@HOST:PORT"
curl.exe https://api.ipify.org

Need one request to skip the proxy while these are set? Add --noproxy "*" to it. To clear the settings on a Mac or Linux, run unset http_proxy https_proxy; in PowerShell, closing the window does the same.

Flags that help when something goes wrong

• -v, for "verbose", prints the whole conversation with the proxy, so you can see if your login was refused.
• -I fetches only the headers, the short note a site sends before the page itself, including the status code that says whether the request worked.
• --connect-timeout 10 stops cURL waiting more than 10 seconds for the proxy, so a dead proxy fails quickly instead of hanging.
• -s hides the progress bar. -sS hides it but still shows errors, which is what you want in a script.

Put together, a tidy test that won't sit there forever looks like this:

curl -sS --connect-timeout 10 -x "http://USER:PASS@HOST:PORT" https://api.ipify.org

Check more than the IP

A changed IP is a good first sign. To be thorough, compare your address with and without the proxy on our What is my IP page, test the proxy in the proxy checker, and run the DNS leak test. That last one matters most for SOCKS, where socks5h keeps your look-ups inside the proxy.

Which type should I pick?

• Testing, learning and small scripts: datacenter proxies are quick and the gentlest on a small budget.
• Sites that expect visitors on home connections, or a steady supply of changing addresses: residential, or residential premium for the hardest cases.

The pricing page shows every type side by side.

Is this allowed?

Fetching public pages with cURL is fine, as long as you're polite about it. Read the site's robots.txt (a file where sites say what automated tools may visit), follow its terms of service, go slowly, and collect only public information you're allowed to use. Build pauses into any loop rather than firing requests back to back. This one fetches three pages with a two-second rest after each:

for i in 1 2 3; do
  curl -sS -x "http://USER:PASS@HOST:PORT" "https://example.com/page/$i"
  sleep 2
done

For bigger projects, rotating residential addresses spread requests across many IPs; our proxies for scraping page and the residential proxy options explain how. Want to check search rankings from different places? The proxies for SEO page covers that setup. Whatever the project, a proxy is never a way to break into logins, collect data from accounts that aren't yours, or ignore a site's rules.

Common mistakes

• Leaving the placeholders in. USER, PASS, HOST and PORT are stand-ins. Replace all four with your own details, and keep the colon and the @ sign where they are.
• Removing the quotation marks. Keep the proxy address inside the quotes, as shown. Without them, some characters in a password can be read by the terminal as instructions.
• Typing plain curl in Windows PowerShell. Use curl.exe there, or switch to Command Prompt.
• Writing socks5 when you meant socks5h. Without the h, look-ups happen on your own computer and can leak.

Beginner questions

Do I need to install cURL?

Probably not. Type curl in your terminal and press Enter. A short hint about how to use it means it's installed.

My browser still shows my real IP. Is the proxy broken?

No. The proxy you give cURL is used by cURL alone. Your browser has its own settings and connects as normal until you change them.

Is it safe to type my password into a command?

On your own computer it's fine. Just know that terminals often keep a history of the commands you type, password included. On a shared computer, IP whitelisting is the tidier choice, because then there's no password to type at all.