How to Use cURL with Proxy

curl is a tool for transferring data using various network protocols, such as HTTP, HTTPS, FTP, SFTP, and IMAP. It’s estimated that curl is installed over twenty billion times worldwide, and it’s currently the most popular tool for network communication.

Used by numerous programming languages, embedded systems, website backends, and games and apps, curl facilitates sending and receiving data over the internet, uploading and downloading files, and interacting with APIs.

In this article, you’ll learn how to use proxy servers with curl.

---

Installing curl

Before you can use curl, you need to install it on your device.

Linux

Some Linux distributions, such as Ubuntu, come with curl preinstalled. Run curl --version in a terminal to check if it’s installed. If you get an output saying “Command not found,” you need to install curl.

The specific process for installing curl depends on the Linux distribution you’re using. You’ll find curl in your distribution’s official package repositories.

Once you’ve located your distribution package, you can use it to install curl. Following are a few examples:

• Ubuntu/Debian: sudo apt install curl
• Fedora/RHEL/CentOS: sudo yum install curl
• OpenSUSE: sudo zypper install curl
• Arch: sudo pacman -Sy curl

Windows

With Windows 10 and newer, curl comes preinstalled with the OS, and you can invoke the curl command from CMD or PowerShell. However, in PowerShell, the curl command is an alias for PowerShell’s own Invoke-WebRequest command. If you want to use the actual curl in PowerShell, you need to invoke curl with curl.exe, which prevents PowerShell from interpreting it as an alias. Additionally, you can remove the alias using rm alias:curl and use the typical curl command.

A common complaint of developers is that the curl shipped with Windows is built and managed by Microsoft and isn’t updated as frequently as the original curl, which means that the curl shipped with Windows often lacks features. If you want to use the latest curl, you can download it from the official curl site. When you extract the files, you’ll find a curl.exe file, which you need to invoke to use curl.

macOS

curl comes preinstalled with macOS, so you don’t need to install it. You can simply invoke curl from the terminal.

Once you’ve installed curl, run curl --version in a terminal to verify that it works. You should see an output that looks like this:

curl 8.7.1 (x86_64-pc-linux-gnu) libcurl/8.7.1 OpenSSL/3.0.13 zlib/1.3.1 brotli/1.1.0 zstd/1.5.6 libidn2/2.3.7 libpsl/0.21.5 libssh2/1.11.0 nghttp2/1.61.0
Release-Date: 2024-03-27
Protocols: dict file ftp ftps gopher gophers http https imap imaps ipfs ipns mqtt pop3 pop3s rtsp scp sftp smb smbs smtp smtps telnet tftp
Features: alt-svc AsynchDNS brotli GSS-API HSTS HTTP2 HTTPS-proxy IDN IPv6 Kerberos Largefile libz NTLM PSL SPNEGO SSL threadsafe TLS-SRP UnixSockets zstd

---

Using Proxies with curl

A proxy server is an intermediate server that sits between the client and the target server. The proxy server interprets requests from the client and forwards them to the target server, effectively hiding the client from the target server. This keeps the anonymity and privacy of the client and helps overcome network restrictions such as geoblocking.

To use a proxy with curl, you first need access to a proxy server. You can use a free proxy or pay for a premium proxy for better security and protection. You need the following information from your proxy server to access it:

• Protocol (HTTP/HTTPS/SOCKS)
• Proxy server host or IP address
• Proxy server port
• Credentials, like username and password, for authentication (optional)

Once you have this information, use it in the following format to create a proxy server URL:

[<PROTOCOL>://][<USERNAME>:<PASSWORD>]@<HOST>[:<PORT>]

In this example, the parts within brackets are optional, and if you omit them, curl uses the following default values:

• If the protocol is omitted, it defaults to HTTP.
• If the port is omitted, it defaults to 1080.
• If the username and password are omitted, authentication is disabled.

Open a terminal and run the following command, which makes a request to https://ifconfig.me and returns the IP address of your device:

curl http://ifconfig.me

You should get an output like this:

103.120.115.2

This is the public IP address of your device. Now, you use a proxy with curl to make the same request.

There are several ways you can set a proxy in curl, but you’ll take a look at the following approaches in this article:

• Using a command line argument
• Using environment variables
• Using a configuration file

Using a Command Line Argument

curl offers the -x and --proxy command line arguments to set up a proxy. You need to pass the proxy server details in the format shown previously. The syntax using -x or --proxy looks like this:

curl -x <PROXY_SERVER_CONFIGURATION> <URL>
# or
curl --proxy <PROXY_SERVER_CONFIGURATION> <URL>

Note: The command line arguments are case-sensitive. Don’t confuse -x with -X.

In your terminal, run the following command:

curl --proxy "http://<YOUR_PROXY_HOST>:<YOUR_PROXY_PORT>" "http://ifconfig.me"

Replace <YOUR_PROXY_IP> and <YOUR_PROXY_PORT> with the appropriate values for your proxy server.

This time, you see a different output, which reflects the IP address of the proxy server. It should look something like this:

76.34.238.134

If your proxy requires authentication, you can pass the username and password in the proxy URL, as shown previously, or you can use the -U/--proxy-user option in curl:

curl --proxy "http://<USERNAME>:<PASSWORD>@<YOUR_PROXY_HOST>:<YOUR_PROXY_PORT>" "http://ifconfig.me"
# Or
curl --proxy "http://<YOUR_PROXY_HOST>:<YOUR_PROXY_PORT>" --proxy-user <USERNAME>:<PASSWORD> "http://ifconfig.me"

As mentioned before, the default proxy protocol is HTTP. If you want curl to proxy the requests through the HTTPS protocol, you need to use https as the protocol in the proxy server URL:

curl --proxy "https://<YOUR_PROXY_HOST>:<YOUR_PROXY_PORT>" "http://ifconfig.me"

Using Environment Variables

curl can use the http_proxy and https_proxy environment variables to set up a proxy using the HTTP and HTTPS protocols, respectively. If you set these environment variables, any subsequent invocation of curl will use these proxies without having to use the --proxy option.

On macOS and Linux, you can set the environment variables using the following syntax:

export http_proxy="http://<USERNAME>:<PASSWORD>@<YOUR_PROXY_HOST>:<YOUR_PROXY_PORT>"
export https_proxy="https://<USERNAME>:<PASSWORD>@<YOUR_PROXY_HOST>:<YOUR_PROXY_PORT>"

On Windows, use the following PowerShell syntax:

$Env:http_proxy = "http://<USERNAME>:<PASSWORD>@<YOUR_PROXY_HOST>:<YOUR_PROXY_PORT>"
$Env:https_proxy = "https://<USERNAME>:<PASSWORD>@<YOUR_PROXY_HOST>:<YOUR_PROXY_PORT>"

Then, run curl ifconfig.me, and curl uses the proxies from the environment variables.

These variables take effect in the same terminal they’re defined in. So if you open another terminal and run curl ifconfig.me, you’ll see your device’s IP address since the environment variables don’t exist in the new terminal. If you want to persist these settings globally, you need to set the environment variables permanently. Take a look at this Stack Exchange question for macOS and Linux and this Microsoft documentation for Windows for more information.

Using a Configuration File

When curl is invoked, it checks for a configuration file and loads default settings from this file. This file is typically named .curlrc, and curl automatically searches a few default locations for this file. You can also use the -K or --config option to specify a custom configuration file. Any command line argument specified in this file is applied automatically.

Note: On Windows, each location is checked for both .curlrc and _curlrc, but the former is preferred.

If you’re using Linux or macOS, create a .curlrc file in the home directory, and if you’re using Windows, create a .curlrc file in the %APPDATA% directory. Then, paste the following content:

proxy="http://<USERNAME>:<PASSWORD>@<YOUR_PROXY_HOST>:<YOUR_PROXY_PORT>"

Save this file and run curl ifconfig.me, and you should see the IP address of the proxy server as before.

Note: If you do not see the expected output, check if you already have another .curlrc file somewhere up the default locations chain that is overriding the proxy settings.

---

Using a SOCKS Proxy

A SOCKS proxy can be used in a similar way as an HTTP or HTTPS proxy using the -x option. The only difference is that the protocol must be socks4, socks4a, socks5, or socks5h:

curl --proxy "socks5://<USERNAME>:<PASSWORD>@<YOUR_PROXY_HOST>:<YOUR_PROXY_PORT>" "http://ifconfig.me"

curl also offers shorthand --socks4, --socks4a, and --socks5 options for specifying a SOCKS proxy. In this case, you omit the -x flag, but you must use the --proxy-user option to supply the credentials:

curl --socks5 "<YOUR_PROXY_HOST>:<YOUR_PROXY_PORT>" --proxy-user <USERNAME>:<PASSWORD> "http://ifconfig.me"

---

Ignoring Proxy for a Single Request

As you saw before, if you use the environment variables or the configuration file, the proxy settings are applied automatically to every request. However, there may be cases where you want to ignore proxies for a single request. You can do this by using the --noproxy "*" argument:

curl --noproxy "*" http://ifconfig.me

---

Quickly Turning Proxies On and Off

Sometimes, you might need to turn off proxies for more than one consecutive invocation. In this case, you can use shell aliases to set up custom commands that can set and unset the http_proxy and https_proxy environment variables.

For example, for Bash shells, add the following lines to your .bashrc:

alias proxyon="export http_proxy='http://<YOUR_PROXY_HOST>:<YOUR_PROXY_PORT>';export https_proxy='http://<YOUR_PROXY_HOST>:<YOUR_PROXY_PORT>'"

alias proxyoff="unset http_proxy;unset https_proxy"

Log out and log back in for the changes to take effect. Now you can use the proxyon and proxyoff commands to turn proxies on and off:

proxyon # Use proxies

curl http://ifconfig.me

proxyoff # Turn proxies off

For PowerShell users, this guide shows how to set aliases.

---

Proxy Chaining

For added security, it’s sometimes desirable to use multiple proxies in a chain. In this setup, the client first connects to proxy 1, which forwards the requests to proxy 2, which forwards them to proxy 3, and so on, until the final proxy sends the request to the target server. Setting up a proxy chain is beyond the scope of this article, but curl provides a --preproxy option that lets you use two proxies in a chain.

If you provide a SOCKS proxy to the --preproxy option and an HTTP/HTTPS proxy to the --proxy option, curl first connects to the SOCKS proxy and then connects (through SOCKS) to the HTTP or HTTPS proxy:

curl --preproxy "socks5://<YOUR_PROXY_HOST>:<YOUR_PROXY_PORT>" --proxy "http://<YOUR_PROXY_HOST>:<YOUR_PROXY_PORT>" ifconfig.me

Note: The --preproxy option accepts a SOCKS proxy only.

---

Conclusion

Often, you need to use proxies to keep the anonymity of your devices and overcome restrictions. Because curl is one of the most popular network communication tools, you’ll likely encounter a situation where you need to use proxies with curl.

In this article, you learned how to use HTTP/HTTPS/SOCKS proxies with curl. You also learned how to use command line options, environment variables, and configuration files to enable proxies. Additionally, you learned how to ignore a proxy for a single request, turn proxies on and off, and use pre-proxies.