Requête HEAD avec curl : récupérer les en-têtes HTTP avec -I et --head

La réponse en bref

Pour envoyer une requête HEAD avec curl, utilisez l’option -I (i majuscule) ou sa forme longue --head. Le serveur renvoie la ligne de statut et les en-têtes, et curl les affiche directement dans votre terminal.

# Forme courte
curl -I https://example.com

# Forme longue (résultat identique)
curl --head https://example.com

Cette seule commande vous donne le code de statut HTTP, le type de contenu, la taille du contenu, la date de dernière modification, ainsi que tous les en-têtes de cache et de sécurité envoyés par le serveur, sans télécharger le moindre octet du corps de la page. Le reste de ce guide explique quand y recourir, comment la combiner avec les redirections et l’authentification, et l’unique erreur qui donne l’impression qu’une requête HEAD est figée.

Aide-mémoire de la requête HEAD avec curl

Mettez ce tableau en favori. Chaque commande est prête à copier-coller, remplacez simplement l’URL par la vôtre.

Qu’est-ce qu’une requête HEAD ?

Une requête HEAD est l’une des méthodes HTTP standard, définie dans la RFC 9110. Elle est identique à une requête GET à une différence essentielle près : le serveur répond avec les mêmes en-têtes qu’il enverrait pour un GET, mais omet le corps du message. Vous obtenez toutes les métadonnées d’une ressource sans transférer la ressource elle-même.

Comme la réponse ne contient aucun corps, une requête HEAD est rapide et peu coûteuse. C’est l’outil adapté dès que vous vous intéressez aux informations sur une ressource plutôt qu’à son contenu, par exemple : cette URL existe-t-elle, quelle est la taille du fichier, quel est son type de contenu, quand a-t-elle été modifiée pour la dernière fois, est-elle mise en cache ou redirigée.

Utilisez -I, pas -X HEAD

Vous verrez deux façons d’envoyer une requête HEAD en ligne. Une seule est fiable.

La bonne méthode est -I / --head. Cette option indique à curl d’émettre une requête HEAD et de n’attendre aucun corps, de sorte qu’il lit les en-têtes et s’arrête proprement.

Le piège, c’est -X HEAD. Cette option remplace le nom de la méthode envoyée au serveur, mais curl attend toujours un corps de réponse et garde la connexion ouverte dans l’attente. Face à certains serveurs, la commande semble se bloquer jusqu’à expiration du délai, et les en-têtes ne sont pas affichés sauf si vous ajoutez aussi -i. Les mainteneurs de curl le déconseillent explicitement.

# Correct : propre et fiable
curl -I https://example.com

# À éviter : peut se bloquer en attente d’un corps, et masque les en-têtes sans -i
curl -X HEAD https://example.com
curl -X HEAD -i https://example.com   # « fonctionne » mais il n’y a aucune raison de le faire

Règle générale : si vous voulez uniquement les en-têtes, utilisez -I. Réservez -X aux méthodes pour lesquelles curl n’a pas d’option dédiée, comme PATCH.

Lire la sortie

Voici une réponse HEAD typique. La première ligne est le statut ; tout ce qui suit est un en-tête.

$ curl -I https://example.com

HTTP/2 200
content-type: text/html; charset=UTF-8
content-length: 1256
last-modified: Mon, 29 Jun 2026 10:14:52 GMT
cache-control: max-age=3600
etag: "3f80f-1b6-3e1cb03b"
server: nginx
date: Tue, 30 Jun 2026 09:00:00 GMT

• HTTP/2 200 : la version du protocole et le code de statut. 200 signifie que la ressource existe et est accessible.
• content-type : le type de média de la ressource (ici, du HTML).
• content-length : la taille du corps en octets que vous téléchargeriez avec un GET, utile pour vérifier la taille avant de récupérer le contenu.
• last-modified / etag : des validateurs de cache qui permettent de détecter si la ressource a changé.
• cache-control : la durée pendant laquelle la réponse peut être mise en cache.

Cas d’usage courants

Vérifier qu’une URL répond (code de statut uniquement)

Pour la supervision ou la vérification de liens, vous ne voulez généralement que le numéro. Jetez le corps, réduisez au silence l’indicateur de progression et affichez le code de statut avec la variable de sortie -w.

curl -I -o /dev/null -s -w "%{http_code}\n" https://example.com
# Sortie : 200

Suivre les redirections jusqu’à la destination finale

Par défaut, curl affiche la première réponse, donc une redirection affiche un 301 ou un 302 puis s’arrête. Ajoutez -L pour suivre l’en-tête Location. Avec HEAD, cela affiche les en-têtes de chaque étape, ce qui permet de retracer toute la chaîne de redirection.

curl -IL http://example.com

# HTTP/1.1 301 Moved Permanently
# location: https://example.com/
#
# HTTP/2 200
# content-type: text/html

Vérifier la taille d’un fichier avant de le télécharger

Lisez l’en-tête content-length pour décider si un téléchargement en vaut la peine, sans avoir à lancer le transfert.

curl -sI https://example.com/large-file.zip | grep -i content-length
# content-length: 5242880

Inspecter un en-tête précis

Redirigez la sortie silencieuse vers grep -i (insensible à la casse, car les noms d’en-têtes ne sont pas sensibles à la casse) pour isoler exactement ce dont vous avez besoin.

curl -sI https://api.example.com | grep -i x-ratelimit
# x-ratelimit-remaining: 4998

Envoyer des en-têtes, une authentification ou un User-Agent personnalisé

Les requêtes HEAD acceptent les mêmes options que n’importe quelle autre requête curl. Combinez-les librement.

# En-tête de requête personnalisé
curl -I -H "Accept: application/json" https://api.example.com

# Authentification basique
curl -I -u username:password https://example.com/private

# Jeton Bearer
curl -I -H "Authorization: Bearer YOUR_TOKEN" https://api.example.com

# Se faire passer pour un navigateur
curl -I -A "Mozilla/5.0" https://example.com

Valider une liste d’URL en masse

Comme HEAD ne télécharge rien, c’est idéal pour vérifier rapidement de nombreux liens dans une boucle shell.

while read url; do
  code=$(curl -I -o /dev/null -s -w "%{http_code}" --max-time 5 "$url")
  echo "$code  $url"
done < urls.txt

# 200  https://example.com
# 404  https://example.com/missing
# 301  https://example.com/old-page

HEAD vs GET avec curl

Les deux méthodes sont volontairement similaires. Le tableau ci-dessous résume quand choisir l’une ou l’autre.

Notez la différence entre les deux options qui se ressemblent : le -I majuscule envoie une requête HEAD et n’affiche que les en-têtes, tandis que le -i minuscule envoie un GET normal et affiche les en-têtes plus le corps.

Quand une requête HEAD échoue

HEAD fait partie du standard HTTP, mais tous les serveurs ne la gèrent pas correctement. Surveillez ces cas :

• 405 Method Not Allowed : le serveur ou le point de terminaison n’autorise pas HEAD. Repliez-vous sur un GET, ou vérifiez les méthodes autorisées, consultez notre guide sur l’erreur 405 Method Not Allowed.
• HEAD est rejeté silencieusement : certains serveurs et CDN répondent à GET mais pas à HEAD. Si une requête HEAD semble incorrecte, confirmez avec un vrai GET (curl -i).
• content-length erroné : quelques serveurs annoncent sur HEAD une taille de corps qui ne correspond pas à celle du GET. Considérez le content-length d’un HEAD comme une forte indication, pas comme une garantie.
• La commande semble se bloquer : vous avez presque certainement utilisé -X HEAD au lieu de -I. Changez d’option.

Foire aux questions

Quelle est la commande curl pour une requête HEAD ?

curl -I https://example.com. L’option -I (ou --head) demande uniquement les en-têtes de la réponse.

Quelle est la différence entre -I et -i avec curl ?

Le -I majuscule envoie une requête HEAD et n’affiche que les en-têtes. Le -i minuscule envoie un GET normal et affiche les en-têtes suivis du corps.

Pourquoi curl -X HEAD se bloque-t-il ?

Avec -X HEAD, curl attend toujours un corps de réponse et patiente pour des données que le serveur n’envoie jamais. Utilisez plutôt -I, qui sait qu’une réponse HEAD n’a pas de corps.

Comment suivre les redirections avec une requête HEAD ?

Ajoutez l’option -L : curl -IL https://example.com. Curl affiche les en-têtes de chaque étape de la chaîne de redirection.

Puis-je envoyer une authentification avec une requête HEAD ?

Oui. HEAD accepte toutes les options d’authentification de curl, par exemple -u user:pass pour l’authentification basique ou -H "Authorization: Bearer TOKEN" pour un jeton.

Comment afficher uniquement le code de statut ?

Combinez HEAD avec la variable de sortie : curl -I -o /dev/null -s -w "%{http_code}\n" https://example.com.

Résumé

Une requête HEAD avec curl est le moyen le plus rapide d’inspecter les en-têtes HTTP d’une ressource : son statut, son type, sa taille, sa date de modification et son cache, sans télécharger le corps. Utilisez curl -I ou curl --head, et évitez -X HEAD, qui peut se bloquer.

À partir de là, ajoutez les options que vous connaissez déjà : -L pour suivre les redirections, -s avec -w pour n’afficher que le code de statut, -H et -u pour les en-têtes et l’authentification, et un tube vers grep pour isoler un seul en-tête. Avec ces quelques motifs, vous pouvez vérifier des liens, superviser la disponibilité, mesurer la taille des fichiers et retracer les redirections, le tout en une seule ligne.