How to set a custom HTTP header in curl

Last updated on September 11, 2020 by Dan Nanni

curl is a powerful command-line tool that can transfer data to and from a server over network. It supports a number of transfer protocols, notably HTTP/HTTPS, and many others such as FTP/FTPS, RTSP, POP3/POP3S, SCP, IMAP/IMAPS, etc. When you send out an HTTP request for a URL with curl, it uses a default HTTP header with only essential header fields (e.g., User-Agent, Host, and Accept).

In some cases, however, you may want to override the default header or even add a custom header field in an HTTP request. For example, you may want to override Host field to test a load balancer, or spoof User-Agent string to get around browser-specific access restriction. In other cases, you may be accessing a website which requires a specific cookie, or testing a REST-ful API with various custom parameters in the header.

To handle all these cases, curl provides an easy way to fully control the HTTP header of outgoing HTTP requests. The parameter you want to use is -H or equivalently --header.

The -H option can be specified multiple times with curl command to define more than one HTTP header fields.

For example, the following command sets three HTTP header fields, i.e., overriding Host field, and add two fields (Accept-Language and Cookie).

$ curl -H 'Host: 157.166.226.25' -H 'Accept-Language: es' -H 'Cookie: ID=1234' http://cnn.com

For standard HTTP header fields such as User-Agent, Cookie, Host, there is actually another way to setting them. The curl command offers designated options for setting these header fields:

• -A (or --user-agent): set User-Agent field.
• -b (or --cookie): set Cookie field.
• -e (or --referer): set Referer field.

For example, the following two commands are equivalent. Both of them change User-Agent string in the HTTP header to my browser.

$ curl -H "User-Agent: my browser" http://cnn.com
$ curl -A "my browser" http://cnn.com

There are also other command-line utilities that you can use to fetch a URL like curl. For example, wget can use a custom HTTP header with --header option. HTTPie offers a more user-friendly interface to generate custom HTTP headers.

Support Xmodulo

This website is made possible by minimal ads and your gracious donation via PayPal or credit card

Please note that this article is published by Xmodulo.com under a Creative Commons Attribution-ShareAlike 3.0 Unported License. If you would like to use the whole or any part of this article, you need to cite this web page at Xmodulo.com as the original source.