How to set a custom HTTP header in curl

Question: I am trying to fetch a URL with curl command, but want to set a few custom header fields in the outgoing HTTP request. How can I use a custom HTTP header with curl?

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:' -H 'Accept-Language: es' -H 'Cookie: ID=1234'

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.

$ curl -H "User-Agent: my browser"
$ curl -A "my browser"

wget is another command-line tool which you can use to fetch a URL similar to curl, and wget also allows you to use a custom HTTP header. Check out this post for details on wget command.

Download this article as ad-free PDF (made possible by your kind donation): 
Download PDF

Subscribe to Ask Xmodulo

Do you want to receive Linux related questions & answers published at Ask Xmodulo? Enter your email address below, and we will deliver our Linux Q&A straight to your email box, for free. Delivery powered by Google Feedburner.

Support Xmodulo

Did you find this tutorial helpful? Then please be generous and support Xmodulo!

Leave a comment

Your email address will not be published. Required fields are marked *