Curl HEAD Request Example — Fetch Headers Only

The command

curl -I https://httpbin.org/get

What the flags do

Flag	What it does
`-I`	Send HEAD and print the response headers. Long form: `--head`.
`-L`	Follow redirects, printing the headers of every hop.
`-s`	Hide the progress meter when piping the headers elsewhere.

What you can learn from headers alone

The status line tells you whether the resource is there. Content-Length is the size of the body you did not download, Content-Type is its format, and Last-Modified and ETag let you decide whether a cached copy is still current. With -L you see each redirect and where it points.

curl -sI https://example.com/installer.dmg | grep -i -E "^(HTTP|content-length|last-modified)"

# every hop of a redirect chain
curl -sIL http://example.com/old-path | grep -i -E "^(HTTP|location)"

When HEAD lies

A server is supposed to answer HEAD exactly as it would GET, minus the body. Many do not. Application routes that only register a GET handler return 405 or 404 to HEAD, some CDNs omit Content-Length, and dynamic pages may report different headers because the body was never generated. If a HEAD result looks wrong, confirm it with a GET that discards the body.

# headers from a real GET, body thrown away
curl -s -o /dev/null -D - https://httpbin.org/get

Checking a list of URLs

Because it transfers no body, HEAD is the economical way to audit many links at once. Print the status code and the URL for each with -w, and let xargs run several requests in parallel. Anything that is not a 200 is worth a second look with a full GET, for the reason above.

printf '%s\n' https://httpbin.org/status/200 https://httpbin.org/status/404 \
  | xargs -P 4 -I{} curl -s -I -o /dev/null -w "%{http_code} {}\n" {}

Common mistakes

Never write -X HEAD. It changes only the method name, so curl still waits for a body that will not come and either hangs or reports a transfer error. -I is the correct flag.
-I cannot be combined with -d. Curl refuses to choose between HEAD and POST. To send query data on a HEAD request, add -G so the data moves into the URL.
Header names are case-insensitive, and HTTP/2 always sends them in lower case, so match with grep -i.

Related curl examples

Curl GET Request Example

GET is what curl does when you give it nothing but a URL.

Curl Follow Redirect Example

Curl does not follow redirects unless asked.

Curl Download File Example

Curl prints what it downloads to the terminal unless told to save it.

Curl OPTIONS Request Example

OPTIONS asks a server what it would accept at a URL.

All Curl Examples

49 worked examples, grouped by what you are trying to do.

More under Methods

References

curl man page: -I — Fetching headers only.
MDN: HEAD — How a HEAD response relates to the GET it mirrors.

These links leave api-tester.com, which is independent of the projects they point to.

FAQ

How do I send a HEAD request with curl?

Use the -I flag (capital i), for example curl -I https://example.com. Curl sends a HEAD request and prints only the response headers.

Why does curl -X HEAD hang?

Because -X only renames the method. Curl still expects a response body, which a HEAD response never has. Use -I instead.

How do I get just the HTTP status code with curl?

Use curl -s -o /dev/null -w "%{http_code}" URL, adding -I if you want to avoid downloading the body.