cURL tourne sur environ 20 milliards d’installations dans le monde — il est intégré par défaut à macOS, à la plupart des distributions Linux, ainsi qu’à Windows 10/11. Pourtant, demande à dix développeurs comment faire passer correctement une requête cURL par un proxy, et tu obtiendras dix réponses légèrement différentes, dont la moitié ne tient plus dès qu’il faut gérer l’authentification ou SOCKS.
C’est précisément cette zone grise que je veux éclaircir ici. La plupart des tutoriels te donnent une commande, te disent que ça marche, puis passent à autre chose. Ils ne te montrent pas comment vérifier que le proxy fait vraiment quelque chose (spoiler : parfois, ce n’est pas le cas), et ils ne t’accompagnent certainement pas pour interpréter les codes d’erreur qui apparaissent dès que ta config s’éloigne un peu du cas idéal. Ce guide couvre tout le sujet — proxys HTTP/HTTPS, SOCKS4/SOCKS5/socks5h, variables d’environnement (et leurs pièges très spécifiques), un vrai tableau de dépannage, ainsi que les solutions quand cURL et un proxy ne suffisent plus à faire le boulot.
Qu’est-ce que cURL et pourquoi l’utiliser avec un proxy ?
cURL est un outil en ligne de commande qui sert à transférer des données vers une URL et depuis une URL. Rien de plus : pas d’interface graphique, pas d’effets de style, juste un programme qui parle HTTP, HTTPS, FTP et quelques autres protocoles. L’appel le plus simple possible ressemble à ceci :
curl https://example.com
Cette commande récupère la page et affiche le HTML brut dans ton terminal. C’est déjà utile, mais la vraie raison pour laquelle les développeurs et les utilisateurs métier techniques adoptent cURL, c’est pour tester des API, extraire des données, vérifier des contenus soumis à des restrictions géographiques et lancer des requêtes dans des pipelines CI/CD.
Un proxy se place entre ta machine et le serveur cible, et relaie ta requête à ta place. Le serveur de destination voit l’adresse IP du proxy, pas la tienne. C’est important pour plusieurs usages légitimes : tester l’affichage d’un site depuis un autre pays, contourner temporairement des limites de débit pendant une phase de QA, ou faire passer le trafic par la passerelle d’entreprise imposée par ton organisation. cURL prend en charge tout l’éventail des protocoles proxy — HTTP, HTTPS, SOCKS4 et SOCKS5 — et les options que tu verras revenir tout au long de ce guide sont -x / --proxy (l’adresse du proxy elle-même), -v (sortie détaillée, ton meilleur allié de débogage) et -k (ignorer la vérification SSL, ce qu’il vaut mieux éviter en dehors des tests).
Une précision avant d’aller plus loin : ce guide traite uniquement des mécanismes réseau liés à l’usage d’un proxy avec cURL. Il ne t’autorise pas à ignorer les conditions d’utilisation d’un site ni les politiques de sécurité de ton organisation. Un proxy change le chemin réseau — pas ce qui est légal ou autorisé.
Avant de commencer
Niveau : Débutant à intermédiaire
Temps nécessaire : environ 15 minutes pour parcourir les exemples principaux
Ce dont tu auras besoin :
- cURL installé (vérifie avec
curl --version— sur macOS, Linux ou Windows 10/11, il est très probablement déjà présent) - Les identifiants de proxy fournis par ton prestataire : hôte, port, protocole (HTTP/HTTPS/SOCKS) et nom d’utilisateur/mot de passe si nécessaire
- Un terminal (Terminal sur macOS, n’importe quel shell sur Linux, PowerShell ou CMD sur Windows)
Si cURL n’est pas installé pour une raison ou une autre, l’installation tient en une ligne : brew install curl sur macOS via Homebrew, sudo apt install curl sur Debian/Ubuntu, ou sudo yum install curl sur RHEL/CentOS. Sous Windows, il est fourni avec le système depuis Windows 10 build 17063.
Dans ce guide, j’utiliserai des valeurs fictives — proxy.example:8080 pour l’adresse du proxy et user:pwd pour les identifiants. Remplace-les par les informations réelles de ton proxy, et ne colle jamais de vrais identifiants dans l’historique du shell, une capture d’écran ou un message Slack. J’ai vu passer plus de mots de passe de proxy divulgués dans Slack que je ne voudrais l’admettre.
Comment utiliser cURL avec un proxy HTTP ou HTTPS
C’est la configuration la plus courante, et celle que tu utiliseras dans l’immense majorité des cas.
Utiliser l’option -x / --proxy
La syntaxe de base ressemble à ceci :
curl -x "http://user:pwd@proxy.example:8080" "https://httpbin.org/ip"
-x et --proxy font exactement la même chose — choisis celle qui te paraît la plus facile à retenir. Comme HTTP est le schéma proxy par défaut de cURL, tu peux techniquement supprimer le préfixe http:// et écrire simplement proxy.example:8080. Je recommande quand même de l’écrire explicitement, parce que dans six mois tu apprécieras cette clarté.
Encadre toute l’URL avec des guillemets doubles. Si ton mot de passe contient un @, un # ou un &, une chaîne non protégée sera modifiée par ton shell avant même que cURL ne la voie.
Se connecter via un proxy HTTPS
Certains fournisseurs chiffrent la connexion jusqu’au proxy lui-même via TLS, et pas seulement entre le proxy et ta cible. C’est différent d’un simple site HTTPS à extraire : le protocole du proxy et celui de la cible sont deux variables indépendantes. Pour le préciser :
curl -x "https://user:pwd@proxy.example:8080" "https://httpbin.org/ip"
Si tu obtiens ici une erreur de certificat, évite l’envie d’ajouter -k et de passer à autre chose. Cette option désactive totalement la vérification du certificat SSL, ce qui peut dépanner un test local de cinq minutes, mais devient une très mauvaise idée dès qu’on touche à la production ou à de vraies données utilisateurs. Si tu utilises un proxy d’entreprise qui intercepte le TLS (une configuration de type MITM, fréquente en environnement corporate), la bonne solution consiste à importer le certificat CA du proxy, pas à désactiver la vérification.
S’authentifier avec --proxy-user
Tu peux aussi séparer les identifiants dans leur propre option au lieu de les mettre dans l’URL :
curl -x "http://proxy.example:8080" --proxy-user "user:pwd" "https://httpbin.org/ip"
Attention : le -U majuscule ne correspond pas à l’authentification du site cible (-u / --user, en minuscules). Les confondre est un excellent moyen d’envoyer le mot de passe de ton proxy au mauvais destinataire. Dans les environnements d’entreprise qui utilisent NTLM ou Digest au lieu de Basic, ajoute --proxy-ntlm ou --proxy-digest avec --proxy-user.
Comment utiliser cURL avec un proxy SOCKS : SOCKS4 vs SOCKS5 vs socks5h
Les proxys SOCKS fonctionnent à un niveau plus bas que les proxys HTTP — ils ne se soucient pas du protocole que tu fais passer par le tunnel, ce qui les rend utiles pour du trafic non HTTP, des circuits Tor et tout ce qui touche à la confidentialité. La plupart des guides concurrents se contentent d’une commande et passent à autre chose. C’est une erreur, car les différences entre SOCKS4, SOCKS5 et socks5h:// sont vraiment importantes.
| Fonctionnalité | SOCKS4 | SOCKS5 | socks5h:// |
|---|---|---|---|
| Prise en charge TCP | Oui | Oui | Oui |
| Prise en charge UDP | Non | Oui | Oui |
| Authentification | Non | Oui | Oui |
| Résolution DNS distante | Non | Non (DNS local) | Oui (résolution par le proxy) |
| Compatible Tor | Non | Risqué (fuite DNS) | Oui |
La ligne sur la résolution DNS est celle qui piège vraiment les gens. Avec socks5://, ta machine résout le nom d’hôte avant de transmettre la connexion au proxy — ce qui signifie que ton résolveur DNS local (et donc, par extension, ton FAI) voit exactement quel domaine tu essaies d’atteindre, même si le trafic HTTP réel passe ensuite par le proxy. socks5h:// corrige cela en confiant la résolution du nom d’hôte au proxy, de sorte qu’aucune information sur la destination ne fuite localement. C’est pour cette raison que la documentation Tor insiste sur socks5h:// — utiliser un simple socks5:// annule une bonne partie de l’anonymat que Tor est censé offrir.
Voici chaque variante dans cURL :
curl --socks4 "proxy.example:1080" "http://example.com"
curl -x "socks5://user:pwd@proxy.example:1080" "http://example.com"
curl -x "socks5h://user:pwd@proxy.example:1080" "http://example.com"
Sauf raison particulière, choisis socks5h:// par défaut. Ça ne coûte rien de plus et ça évite une fuite que tu n’aurais sinon jamais remarquée.
Définir un proxy avec des variables d’environnement (et éviter les pièges)
Mettre -x sur chaque commande devient vite lassant. Les variables d’environnement te permettent de définir le proxy une seule fois par session shell, puis de laisser chaque appel cURL hériter automatiquement de ce réglage — le manuel de cURL documente http_proxy, HTTPS_PROXY, ALL_PROXY et NO_PROXY comme ensemble pris en charge.
Les bases
export http_proxy="http://user:pwd@proxy.example:8080"
export HTTPS_PROXY="http://user:pwd@proxy.example:8080"
export ALL_PROXY="socks5h://proxy.example:1080"
Voici le point qui piège constamment les utilisateurs : le nom de la variable fait référence au protocole de l’URL cible, pas à celui du proxy. Ainsi, http_proxy s’applique aux requêtes vers des URL http://, et HTTPS_PROXY aux requêtes vers des URL https:// — tu peux très bien pointer les deux vers le même serveur proxy HTTP, et c’est tout à fait normal.
Contourner avec NO_PROXY
export NO_PROXY="localhost,127.0.0.1,.internal.example"
Les éléments sont séparés par des virgules, et le point au début de .internal.example agit comme un joker pour tous les sous-domaines. NO_PROXY prend le dessus sur tout le reste — même si -x est explicitement indiqué sur la ligne de commande, une correspondance dans NO_PROXY contournera le proxy pour cette requête.
Les pièges qui font vraiment trébucher les gens
- Oublier
export. Si tu tapes simplementhttp_proxy=http://...sansexport, la variable n’existe que dans ton shell actuel et reste totalement invisible pour cURL en tant que processus enfant. C’est, d’après mon expérience, la cause la plus fréquente des tickets de support du type « le proxy ne fonctionne pas ». - La casse des variables. cURL vérifie d’abord spécifiquement
http_proxyen minuscules et lui donne la priorité si les deux versions existent. Certains autres outils ne lisent que la version en majuscules. Si tu cherches pourquoi une variable n’est « pas prise en compte », vérifie qu’il n’existe pas une doublure avec une casse différente. - Le piège de l’alias PowerShell. Dans PowerShell 5.1, taper
curln’appelle pas cURL du tout — cela lanceInvoke-WebRequest, un outil complètement différent avec d’autres options. Si ton option-xprovoque des erreurs étranges sous Windows, tape explicitementcurl.exepour être sûr d’exécuter le vrai cURL. - Les différences de syntaxe sur Windows. CMD utilise
set http_proxy=...; PowerShell utilise$env:http_proxy = "...". Les confondre d’un terminal à l’autre suffit à te faire perdre une après-midi. - Les variables obsolètes.
unset http_proxyetunset https_proxysuppriment une vieille configuration de proxy qui continue silencieusement à router — puis à faire échouer — toutes tes requêtes.
Pour activer ou désactiver rapidement le proxy, quelques alias dans ton .bashrc font gagner un vrai temps :
alias proxyon='export http_proxy="http://proxy.example:8080"; export https_proxy="http://proxy.example:8080"'
alias proxyoff='unset http_proxy; unset https_proxy'
Forcer cURL à toujours utiliser un proxy (fichier de configuration)
Si tu es derrière un proxy d’entreprise 95 % du temps, un fichier .curlrc (sur les systèmes de type Unix, dans ton dossier personnel) ou _curlrc (sous Windows, dans le dossier app-data) permet de définir une valeur par défaut persistante sans toucher aux variables d’environnement :
proxy="http://proxy.example:8080"
Pour toute requête ponctuelle où tu veux l’ignorer, --noproxy "*" annule la configuration pour cet unique appel. La priorité suit généralement l’ordre : option en ligne de commande > variable d’environnement > fichier de configuration, donc -x sur la ligne de commande gagne toujours en cas de conflit.
Attention importante : n’inscris pas de mot de passe en clair dans .curlrc s’il est stocké dans un endroit susceptible d’être synchronisé, sauvegardé ou ajouté par erreur à un dépôt. Pour les pipelines CI, utilise plutôt le gestionnaire de secrets de ta plateforme et injecte les identifiants sous forme de variables d’environnement masquées.
Comment vérifier que votre proxy fonctionne vraiment
C’est la partie que presque tous les autres guides sautent, alors qu’elle fait gagner le plus de temps en débogage. Configurer un proxy et supposer qu’il relaie bien le trafic est la meilleure recette pour passer des heures à chercher pourquoi un scraper ne l’utilisait en fait jamais.
Méthode 1 : comparer votre IP de sortie
Lance deux fois la même requête qui renvoie l’IP — une fois en direct, une fois via le proxy — puis compare :
curl https://httpbin.org/ip
curl -x "http://user:pwd@proxy.example:8080" https://httpbin.org/ip
Si les deux commandes renvoient la même adresse IP, ton proxy ne fait rien. Vérifie la syntaxe de l’option, tes variables d’environnement, ou le fait que NO_PROXY ne correspond pas par erreur à ta cible.
Méthode 2 : lire la sortie verbeuse
Ajoute -v à n’importe quelle requête proxy et cURL affichera tout le handshake :
curl -v -x "http://user:pwd@proxy.example:8080" https://httpbin.org/ip
Cherche une ligne du type * Connected to proxy.example (xx.xx.xx.xx) port 8080, suivie de > CONNECT httpbin.org:443 HTTP/1.1, puis finalement < HTTP/1.1 200 Connection established. Cette séquence — connexion au proxy, puis tunnel CONNECT vers la cible — correspond au méthode HTTP CONNECT en action, et c’est exactement ce qui doit se produire lorsqu’une cible HTTPS passe par un proxy HTTP. Si la ligne CONNECT n’apparaît jamais, l’option proxy n’est pas appliquée. Prudence aussi pendant ce débogage : n’utilise -v que lorsque tu enquêtes activement, et masque la sortie avant de la partager, car le mode verbeux peut afficher les identifiants du proxy en clair.
Méthode 3 : comparer les résultats côte à côte
Pour les tests géographiques en particulier, enregistre les deux sorties dans des fichiers puis fais un diff :
curl https://httpbin.org/ip > direct.json
curl -x "http://user:pwd@proxy.example:8080" https://httpbin.org/ip > proxied.json
diff direct.json proxied.json
Si le corps de réponse — ou les en-têtes, pour du contenu soumis à une restriction géographique — diffère, tu as une confirmation visuelle que le proxy modifie bien le chemin réseau : une méthode rapide et peu coûteuse pour lever le doute avant d’aller plus loin.
Résoudre les erreurs proxy cURL les plus courantes
La plupart des guides évoquent ce sujet à la légère et mentionnent -k une seule fois. Il mérite un vrai tableau de référence.
| Erreur | Cause probable | Correctif |
|---|---|---|
curl: (7) Failed to connect | Mauvais hôte/port de proxy, ou proxy indisponible | Vérifie l’adresse ; teste la connectivité brute avec telnet host port ou nc -zv host port |
407 Proxy Authentication Required | Identifiants proxy manquants ou incorrects | Ajoute --proxy-user user:pass ; vérifie si le fournisseur exige NTLM/Digest/Negotiate au lieu de Basic |
curl: (56) Recv failure: Connection reset by peer | Le proxy a coupé la connexion en cours de transfert | Vérifie la stabilité du proxy avec le fournisseur ; si le proxy termine le TLS, contrôle le traitement des certificats au lieu de désactiver la vérification |
curl: (28) Connection timed out | Pare-feu bloquant, proxy obsolète ou mauvais port | Lance env | grep -i proxy pour repérer d’éventuelles variables résiduelles ; supprime les anciennes valeurs ; teste une requête directe pour isoler la cause |
| Échec de vérification du certificat | Certificat du proxy non approuvé ou interceptant | Récupère la bonne chaîne CA et utilise --proxy-cacert ; évite de désactiver la vérification en dehors d’un diagnostic ponctuel |
Le premier réflexe universel pour ce type d’erreur consiste à ajouter -v. Cela t’indique exactement à quel stade la connexion échoue — résolution DNS, connexion TCP, handshake TLS ou échange d’authentification avec le proxy — au lieu de te laisser deviner à partir d’un code à trois chiffres.
Pour les proxys d’entreprise, --proxy-ntlm et --proxy-negotiate couvrent les schémas d’authentification des domaines Windows. Une chose que cURL ne gère pas nativement : les fichiers PAC (Proxy Auto-Config), ces scripts que certaines entreprises utilisent pour attribuer dynamiquement des proxys. Si ta société en utilise un, tu devras extraire manuellement l’hôte et le port du proxy réel — généralement depuis les paramètres réseau de ton navigateur — puisque cURL n’intègre pas d’analyseur PAC.
Quand cURL + un proxy ne suffisent plus
cURL avec un proxy gère très bien le HTML statique, les appels d’API REST et les récupérations de données simples. Il atteint ses limites face aux défenses favorites du web moderne : applications monopage rendues en JavaScript, systèmes anti-bot comme Cloudflare ou Akamai, et pages verrouillées par CAPTCHA. Envoie cURL vers une application React ou Vue protégée par l’un de ces systèmes, et tu récupéreras un simple <div id="root"></div> vide — requête techniquement réussie, données pratiquement inutilisables. Ce n’est pas un bug de cURL. Ce n’est juste pas un navigateur, et il n’a jamais prétendu l’être.
Si tu sais déjà utiliser cURL depuis un terminal et que tu butes sur cette limite, l’étape naturelle suivante n’est pas de changer complètement de chaîne d’outils — c’est d’ajouter une couche qui gère le rendu et la structuration pour toi. C’est exactement l’écart que les outils développeur de Thunderbit ont été conçus pour combler.
| Scénario | cURL + Proxy | Thunderbit API (POST /extract) |
|---|---|---|
| Page HTML statique | Fonctionne parfaitement | Fonctionne aussi, avec données structurées |
| SPA rendue en JS | Récupère du HTML vide ou partiel | renderMode: "full" gère le JavaScript |
| Anti-bot / CAPTCHA | Bloqué | Traitement intégré |
| Sortie structurée | HTML brut — à parser soi-même | JSON via votre propre schéma |
| Traitement par lot (100+ URL) | Boucle manuelle + limitation de débit à gérer soi-même | POST /batch/extract |
L’Open API de Thunderbit expose un endpoint /extract qui renvoie directement du JSON conforme à ton schéma à partir de pages riches en JavaScript, ainsi qu’un endpoint /distill pour convertir proprement en Markdown — les deux sont appelables depuis exactement la même session terminal où tu exécutes déjà tes commandes cURL. Il existe aussi un serveur MCP pour les assistants de codage IA comme Claude ou Cursor, ainsi qu’une CLI (npx @thunderbit/thunderbit-cli extract <url> --schema fields.json) si tu préfères rester entièrement dans des scripts. Rien de tout cela ne remplace cURL pour les usages où cURL excelle — cela prend simplement le relais là où cURL ne peut structurellement pas aller plus loin. Si tu veux une vision plus large de la place de l’extraction assistée par IA par rapport à l’écriture de ta propre logique de scraping, notre article sur le web scraping avec IA et notre comparatif des meilleurs extracteurs web IA approfondissent le sujet, et notre guide sur le web scraping sans coder constitue une bonne base si tu abordes la question sous un angle métier plutôt qu’ingénierie.
Conclusion
Faire communiquer correctement cURL et un proxy n’a rien de difficile dès lors que tu sais où se trouvent les vrais points de rupture — et il se trouve qu’ils concernent presque toujours autre chose que le proxy lui-même. Oublier export. Confondre -u avec -U. Utiliser socks5:// alors que tu voulais socks5h://. Lancer l’alias curl de PowerShell au lieu de curl.exe. Chacune de ces erreurs produit un message confus et générique qui n’a souvent rien à voir avec le fournisseur de proxy.
L’habitude la plus rentable en temps : vérifier avant de dépanner. Lance le test d’écho d’IP, jette un œil à la sortie de -v, confirme que le proxy est bien sur le chemin de la requête avant de supposer qu’un problème se trouve en aval. Et lorsque ta cible commence à te renvoyer du JavaScript au lieu de HTML propre, ce n’est plus un problème de cURL à résoudre avec davantage d’options — c’est le signal qu’il faut utiliser un outil pensé pour le rendu, comme l’API de Thunderbit, qui propose une formule gratuite si tu veux constater par toi-même la différence entre JSON en sortie et HTML brut.
FAQ
cURL utilise-t-il un proxy par défaut ?
Non. Sauf si tu as défini des variables d’environnement http_proxy / HTTPS_PROXY ou configuré un fichier .curlrc, cURL se connecte directement à la cible sans passer par un proxy.
Comment empêcher cURL d’utiliser un proxy pour une seule requête ?
Ajoute --noproxy "*" à cette commande précise. Pour le désactiver sur toute la session shell, exécute unset http_proxy && unset https_proxy.
Puis-je utiliser cURL avec des proxys rotatifs ?
Oui — si ton fournisseur propose une passerelle rotative (un point d’entrée unique qui attribue une nouvelle IP à chaque requête), il suffit de pointer -x vers cette passerelle comme vers n’importe quel autre proxy. Pour des logiques de rotation plus complexes sur des cibles rendues en JavaScript, une couche API comme celle de Thunderbit gère en interne la rotation et la partie anti-bot, ce qui t’évite de coder toi-même la logique de retry.
Pourquoi socks5:// fuit-il mes requêtes DNS alors que socks5h:// ne le fait pas ?
Avec socks5://, ta machine locale résout le nom d’hôte de destination avant d’envoyer la demande de connexion au proxy — ce qui signifie que le résolveur DNS de ton FAI voit le domaine que tu visites. socks5h:// délègue la résolution du nom d’hôte au proxy lui-même, de sorte qu’aucune information sur la destination n’est visible localement.
Est-il légal d’utiliser cURL avec un proxy ?
Utiliser un proxy est légal dans la plupart des juridictions en soi. Ce qui compte, c’est ce que tu en fais — respecte toujours les conditions d’utilisation du site cible, le fichier robots.txt lorsque cela s’applique, ainsi que toute législation pertinente en matière de protection des données. Ce guide ne couvre que la mécanique technique, pas une validation juridique d’un usage particulier.
En savoir plus
