Using Curl with a Proxy Server

To use a proxy with Curl, you must pass the required proxy address using the -x (or --proxy) command-line option and proxy credentials using the -U (or --proxy-user) command-line switch. Proxy credentials may also be passed in the proxy string and will be URL decoded by Curl. The proxy string can be prefixed with protocol: //, for example, http:// or socks5://. If no protocol is specified, Curl will default to http://. If no port number is specified in the proxy string, Curl will default to 1080. Click Run to execute the Curl Proxy Server request online and see the results.
Using Curl with a Proxy Server Run
   -U login:password
Updated: Viewed: 41463 times

What is Curl?

Curl is a command-line tool that allows users to transfer data over the network. Curl supports over 25+ protocols, including HTTP, HTTPS, FTP, and SFTP. When it comes to debugging network requests and APIs calls, Curl is one of the best tools out there, and it's free and open-source. Curl works on Linux, Mac, and Windows.

What is a Proxy Server?

A proxy server is an intermediate server (software or hardware) between the user (browser, mobile app, etc.) and the website and transfers traffic between them. Proxies separate end-user clients from the websites they browse and provide multiple levels of functionality and security. For example, proxy servers can compress and encrypt network traffic, prevent intrusion into a local network from the Internet, and monitor employee Internet use during working hours. The word "proxy" means "to act on behalf of another," and the proxy server acts on behalf of the end-user. When using proxy servers, all requests to the Internet first go to the proxy server, which evaluates the request, applies a set of rules to it, and then, if necessary, forwards the request to the Internet. Likewise, server responses are first returned to the proxy, which evaluates and processes them before they are sent to the end-user. In some cases, a chain of proxy servers is used to provide greater anonymity on the Internet.

Does Curl support proxies?

Yes, Curl supports proxies via the -x or --proxy command line option. It is recommended that you enclose the proxy server address in double quotes to handle special characters in the URL correctly. Note that the default proxy protocol for Curl is HTTP.

Curl Proxy Request Syntax

The general form of the Curl command to send a request through a proxy server is as follows:

Curl Proxy Syntax
curl -x "[protocol://][host][:port]" [URL] [options]

Passing Proxy Address to Curl via Environment Variables

Another way to pass the proxy address to Curl is to set the http_proxy and https_proxy environment variables. Using these environment variables will have the same effect as using the -x --proxy command line option. Just keep in mind that command line options are more powerful and override parameters set via environment variables.

Curl Proxy Settings via Environment Variables
export http_proxy="[protocol://][host][:port]"
export https_proxy="[protocol://][host][:port]"

To disable global proxy settings, unset these two environment variables.

unset http_proxy
unset https_proxy

What is an Environment Variable?

An environment variable is a key=value pair that is set at the system level and can affect the behavior of all running processes on the computer. Environment variables are the part of the operating system in which a process runs. Environment variables were first introduced in 1979 on Unix and are now supported by all operating systems, including Linux, macOS, and Windows.

How to bypass SSL certificate errors when using Curl Proxy?

If Curl gets an SSL certificate error, it will automatically block the request. For debugging purposes, to allow insecure connections to the server, you can tell Curl to ignore SSL certificate errors by adding the -k command-line option to the curl request.

Allow Insecure SSL Connections for Curl Proxy Requests
curl -x "[protocol://][host][:port]" -k [URL]

How to make Curl use a proxy via the .curlrc file?

To avoid passing the proxy address every time you run a Curl command, you can create a Curl configuration file (.curlrc) containing multiple configuration parameters and place it in the user's home directory. The next time you run Curl, it will look for the ~/.curlrc file, and if it finds that file, it will load the provided options from the config file. To pass the proxy address through the config file, create a .curlrc in your home directory and enter the proxy address as follows:

Proxy Address in .curlrc File
# --- Proxy example file ---
proxy = "[protocol://][host][:port]"

How to ignore proxies for a single Curl request?

Suppose the proxy is set globally via an environment variable or .curlrc file. In that case, you can still bypass it for specific Curl requests by using the –noproxy "*" command-line parameter in the Curl request.

Disable Proxy for Specific Curl Requests
curl --noproxy "*"

What is a SOCKS Proxy?

SOCKS (Socket Secure) is a network communication protocol that directs any traffic generated by an application to a real server on behalf of the client. A SOCKS proxy server creates a Transmission Control Protocol (TCP) connection with another server and exchanges network packets between the client and the server. SOCKS can handle several types of requests and transparently transfer data for HTTP, HTTPS, POP3, SMTP, FTP, and SFTP streams. There are only two versions of the SOCKS protocol: SOCKS4 and SOCKS5. The main differences between SOCKS5 and SOCKS4 are:

  • SOCKS5 supports multiple authentication methods; SOCKS4 does not support authentication;
  • SOCKS5 supports UDP proxy; SOCKS4 does not support UDP proxy;
  • SOCKS5 is more secure because it uses authenticated TCP connections and SSH-encrypted tunnels;


Curl SOCKS Proxy Syntax
curl -x "[socks5://][host][:port]" [URL] [options]

For Curl SOCKS proxies, you can use the –socks5 command line parameter instead of -x.

Curl SOCKS Proxy Syntax
curl --socks5 "[host][:port]" [URL] [options]

What is Proxy-Authorization?

Proxy authorization is a built-in HTTP mechanism called proxy authentication that prevents unauthorized use of the proxy server and blocks requests from clients to the proxy until the user provides valid credentials to access the proxy. Proxy server authorization is accomplished by sending the Proxy-Authorization HTTP request header from the client to the proxy server.

Proxy Authorization Syntax
Proxy-Authorization: [type] [credentials]
Proxy-Authorization: Basic bG9naW46cGFzc3dvcmQ=

How to specify proxy username and password for Curl?

If your proxy requires user authentication, you can pass the username and password to Curl with the -U or --proxy-user command-line switch.

Curl Proxy Authentication
curl -x "[protocol://][host][:port]" [URL] -U login:password

See also

Generate Code Snippets for Curl Proxy Server Example

Convert your Curl Proxy Server request to the PHP, JavaScript/AJAX, Node.js, Curl/Bash, Python, Java, C#/.NET code snippets using the ReqBin code generator.