The Practical Guide to Using cURL with a Proxy (+ code snippets)

Written by: Robin Geuens

Web scraping is a vital aspect of data gathering in the digital age. Let's explore cURL, a command-line tool widely adopted for this purpose.

Think of it as your digital Swiss Army knife for data retrieval over the internet.

Table of contents

cURL Basics

cURL, or client URL, is a command-line tool that allows you to transfer data using various protocols. The beauty of this tool is that it comes pre-installed on modern systems like Windows 10, macOS, and many Linux distributions.

For those using older Windows versions, have no fear. You can easily download cURL directly from the official website. Once the package is downloaded, simply unzip it to install.

If you're operating on a Debian-based Linux distribution, such as Ubuntu, you can install cURL by running the following command in your terminal:

sudo apt install curl  

For other Linux distributions, you'll want to refer to the specific instructions provided in your distribution's official documentation.

Basic Syntax of cURL

Now that you have cURL installed, let's break down its basic syntax. A typical cURL command consists of:

  • Protocol: The internet protocol for the proxy server (if you're using one)

  • Host: The proxy server's hostname, IP address, or URL

  • Port: The proxy server's port number

  • URL: The URL of the target website the proxy server will communicate with

  • username: Required if the proxy server requires authentication

  • password: Also needed if the proxy server requires authentication

Here's a basic example of a cURL command without a proxy, usernames, or passwords:


This command retrieves the HTML content of a website with the URL of

How to Use cURL with a Proxy

A proxy server acts as a middleman between your computer and the internet. It intercepts your requests and serves them on your behalf. This can be particularly useful in avoiding IP-based blocking.

Let's start with a basic example of a cURL command with a proxy:

curl -x http://proxyserver:port   

In this command, replace "proxyserver" and "port" with your proxy server's IP address and port number, respectively, and "" with the URL you want to request.

You can choose between using -x or --proxy, both mean the same thing.

Different Types of Proxies and How to Use Them

There are primarily three types of proxies you might encounter:

  • HTTP Proxy: This type of proxy is used for HTTP requests. To use an HTTP proxy with cURL, simply follow the example above.

  • HTTPS Proxy: This is similar to an HTTP proxy, but it's used for HTTPS requests. To use an HTTPS proxy, replace "http" with "https" in the proxy server URL:

curl -x https://proxyserver:port   
  • SOCKS Proxy: This type of proxy can handle any type of request, including HTTP, HTTPS, FTP, and more. To use a SOCKS proxy with cURL, you can use the -x flag followed by the SOCKS protocol (either socks4:// or socks5://), the proxy server's IP address, and the port number:

curl -x socks5://proxyserver:port   

Authenticating with a Proxy Server

If you're using a proxy server from a provider like SOAX, you'll need to authenticate yourself to proxy servers. There are two common methods for doing this: Basic authentication and Digest authentication.

Basic Authentication
Basic authentication is the simplest method, which uses a username and password encoded in base64. With cURL, you can pass the username and password as part of the URL:

curl -x http://username:password@proxyserver:port   

Alternatively, you can use the -u flag:

curl -u username:password -x http://proxyserver:port   

Digest Authentication
Digest authentication is a more secure method that uses a cryptographic hash of the username, password, and a server-specified nonce value. To use Digest authentication with cURL, you can use the --digest flag and provide the username and password with the -u flag:

curl --digest -u username:password -x http://proxyserver:port  


Using Rotating Proxies

If you're familiar with web scraping, you know that rotating proxies can be your best ally against IP blocking, rate limiting, and the dreaded captcha challenges.

Essentially, rotating proxies switch their IP address either after each request or at predetermined intervals.

This helps to keep your scraping activities under the radar. But, how can you put them to good use with cURL? Let's dive right in.

Using a Dedicated List of Proxies
The first method involves using a dedicated list of proxies. This could be a list you own or one that you rent from a proxy provider like SOAX.

The advantage of this approach is that you have more control over the proxy url, selection, configuration, and rotation. However, it also means you'll have to shoulder the responsibility of managing the proxy list yourself.

To use this method, you'll need to write a script that can read the proxy list from a file or a database. It should select a proxy randomly or sequentially, and pass it to cURL as an argument to the --proxy option.

Remember, you'll also need to handle the proxy authentication, error handling, and retry logic in your script. This might sound complicated, but with a little practice, it becomes second nature.

Consider this simple script that uses a dedicated proxy list with cURL:

IFS=$'\n' readarray -t proxies < proxies.txt
for p in "${proxies[@]}"; do
  num_proxies=$((num_proxies + 1))
rand_index=$((RANDOM % num_proxies))
curl --proxy "$proxy"


Using an API that Handles the Rotation for You
The second method to use rotating proxies with cURL is by using an API that handles the rotation for you. This can be an invaluable time-saver as the service takes care of the proxy server IP, rotation, geo-targeting, and authentication.

To use this method, you simply pass the proxy URL as an argument to the --proxy option with cURL. The API key or username and password for authentication can be provided with the --proxy-user option.

Here's an example of a cURL command with an IP rotation proxy API:

curl --proxy --proxy-user username:password   

In this proxy command, is the proxy URL and username:password is the authentication information.

By using either of these methods, you can effectively use rotating proxies with cURL. Whether you choose to use a dedicated list of proxies or an API to handle the rotation is entirely up to your specific needs and how much control and management you want over your proxies.

Best Practices for Working with cURL

Setting Environment Variables

One of the best ways to streamline your work with cURL and a curl proxy server, is by setting your proxy server URLs, usernames, and passwords as environment variables.

This approach has the dual benefits of saving you time—since you won't need to manually enter these details each time—and improving security by keeping sensitive data out of your command line history.

Here's how you can set environment variables in a Unix-like environment, such as macOS or Linux:

export HTTP_PROXY=   
export HTTPS_PROXY=   
export FTP_PROXY=   

On Windows, you can accomplish the same task using set instead of export:

set FTP_PROXY=  

Once set, cURL will automatically use these environment variables whenever you execute a command—no manual input required.

Creating Aliases for Common cURL Commands

To further boost your productivity, create aliases for your most frequently used cURL commands.

An alias is essentially a shortcut, allowing you to execute a command with a shorter name—reducing typing errors and saving precious time.

For example, if you find yourself often using the command curl -v -x, you could set up an alias like this:

alias curlproxy='curl -v -x'   

Now, you can simply type curlproxy followed by your URL instead of writing out the full command.

Using a .curlrc File for Streamlined Proxy Set Up

Looking for an even more streamlined setup? Try using a .curlrc file to store your proxy settings and other preferences. This handy configuration file, which is located at home/<username>/ on Mac and c/Users/<username> on Windows, applies default options to your cURL commands.

Here's an example of what a .curlrc file might look like:

proxy = ""   
user-agent = "Mozilla/5.0"   

By incorporating these best practices into your workflow, you can improve the efficiency, security, and reliability of your cURL usage when working with a proxy. A bit of initial setup can go a long way in enhancing your productivity and maintaining the security of your code.

Advanced cURL Tips

Sometimes, the world of web scraping can feel like traversing a dense jungle, especially when dealing with proxies. But fret not because I'm about to share with you some advanced cURL tips that will make your journey a lot smoother.

Bypassing Proxies with cURL

There are moments in your web scraping adventures when you might need to bypass a proxy server to access a website or a resource. This could be for various reasons - testing, debugging, or circumventing proxy restrictions.

Thankfully, cURL offers a couple of straightforward options for this: the --noproxy option and the no_proxy environment variable.

Using the --noproxy Option
Let's say you want cURL to ignore proxy settings for a specific domain. In that case, you can use the --noproxy option, accompanied by the domain name. Here's a real-life example:

curl --noproxy ""   

In this command, cURL will graciously bypass the proxy for

Harnessing the no_proxy Environment Variable
Alternatively, you can set the no_proxy environment variable to a list of domains where cURL should ignore the proxy settings. This method comes in handy when you have several domains to bypass, kind of like having a VIP list for a nightclub. Here's how it works:

export no_proxy=","   

After executing this command, any cURL command you run will ignore the proxy settings for and

Setting Headers in cURL

Headers are like the secret handshakes of the web, providing additional information that can influence how the server or client treats your data.

To set headers in cURL, use the -H or --header option, followed by the header name and value. You can set multiple headers by using the -H option multiple times. Here's an example:

curl -H "Content-Type: application/json" -H "Accept: application/json"   

This command will send a request to with Content-Type and Accept headers set to application/json.

Adding a User-Agent in cURL

The User-Agent is a header that identifies the client software making the request. It's like your web ID card, and it helps the server provide a suitable response for different types of clients.

Sometimes, you may want to change your User-Agent to mimic a browser or another client. This can be handy to avoid being blocked or limited by some websites. To do this, use the -A or --user-agent option, followed by the User-Agent string. Here's how:

curl -A "Mozilla/5.0"   

In this command, cURL will send a request to with the User-Agent set to Mozilla/5.0, which mimics a popular web browser.

Managing Cookies in cURL

Cookies are tiny breadcrumbs of data that websites store on your browser to remember your preferences, settings, or login information. They can also be used for tracking your online activity and behavior.

But how do you deal with these cookies while using cURL?

In cURL, you can use the -b or --cookie option, followed by the cookie name and value. This allows you to send a cookie to the server. For example, if you're sending a cookie named session with value 12345, your command line argument would look like this:

curl -b "session=12345"   

But what if you want to save cookies from a server response? No worries, cURL has got you covered. Use the -c or --cookie-jar option to save the cookies from the server response to a file.

You can then use that file with the -b option to send them back in subsequent requests. Neat, right?

Following Redirects in cURL

When you send a request to a URL, the server might redirect you to another location. This can be troublesome if the redirect location contains the actual content you want, as you might end up with missing or incomplete data.

But don't despair! You can make cURL follow redirects using the -L or --location option. Here's how it's done:

curl -L  

With the -L or --location option, cURL will follow any Location: headers in the response until it reaches the final destination. This ensures that you fetch all the data you need, even if it's tucked away behind several redirects. So, next time you're facing redirect issues, remember this trick!

Ignoring SSL Certificate Errors with cURL

By default, cURL checks the SSL certificates when making HTTPS requests. This is a good safety measure, but can pose problems if you're dealing with expired, self-signed, or untrusted certificates.

To bypass this, you can use the -k or --insecure option. This allows cURL to skip the certificate verification. While this isn't recommended for sensitive operations, it can come in handy when dealing with problematic certificates.

Here's a sample code:

curl -k  

Sending Data with POST Requests in cURL

POST requests are commonly used for submitting forms, uploading files, or creating new resources on a server. With cURL, you can send data with POST requests using the -d or --data option.

To send a string of data, you'd use a command like this:

curl -d "name=John&age=30"   

If you need to send multiple types of data in the same request, the -F or --form option comes in handy. This allows you to send multipart/form-data, which can include both text and files.

Handling Non-2xx/3xx Responses with the -f Flag in cURL

As a developer, you might encounter scenarios where you need non-2xx/3xx responses to be treated as errors. This is where the -f flag in cURL comes into play.

When you use the -f flag, cURL doesn't display an error message for server responses in the 4xx or 5xx range. Instead, it returns an exit code that can be captured and processed in your script. This makes error handling more streamlined and consistent.

Here's a quick look at how you can use this flag:

curl -f   

Disabling the Progress Meter with the -sS Flags in cURL

By default, cURL displays a progress meter when it's not writing to a terminal. However, there are times when you may want to hide the progress meter to clean your output and focus on your data extraction.

The -sS flags can help you achieve this. The -s flag silences cURL, hiding the progress meter, while the -S flag shows errors only.

Here's an example:

curl -sS   

Parsing JSON Data in cURL with jq

When working with APIs, you'll often deal with JSON data. This is where jq, a command-line tool that lets you filter, transform, and manipulate JSON data, comes in handy. Note that jq doesn't come preinstalled, you can download it here.

With jq, you can easily extract specific values from JSON responses with cURL. Here's an example:

curl -sS | jq '.key'   

Saving Results to a File in cURL

Finally, cURL lets you save your logs using the -o or --output option. This can be particularly useful when you're running lengthy processes and want to review the logs later.

Here's how you can save your cURL log to a file:

curl -o log.txt   

Wrapping Up

Mastering cURL might seem daunting at first, but it's a powerful tool that can help streamline your development process. 

With just a basic knowledge of cURL, you can handle HTTP errors consistently, parse JSON data, and save logs for later review. As you continue your journey as a developer, these skills will prove invaluable.

Robin Geuens

Robin is the SEO specialist at SOAX. He likes learning new skills and automating things with Python and GPT. Outside of work he likes reading, playing videogames, and traveling.

Contact author