Utiliser un proxy en Python, Node.js et cURL : exemples de code

Dans un script, utiliser un proxy ne demande que quelques lignes, à condition de connaître la syntaxe de chaque outil et les pièges qui font perdre des heures : une clé mal choisie, un mot de passe mal encodé, un délai d'attente oublié. Voici des exemples complets pour cURL, Python et Node.js, les bonnes pratiques de production et les solutions aux erreurs courantes.

Avant de commencer : l'adresse du proxy

Un accès proxy tient en quatre informations : hôte, port, identifiant et mot de passe. Airproxy les livre au format hôte:port:identifiant:mot de passe, mais la plupart des bibliothèques attendent une URL :

# Ligne livrée
hote.exemple:8080:identifiant:motdepasse

# Adresse pour un proxy HTTP(S)
http://identifiant:motdepasse@hote.exemple:8080

# Adresse pour un proxy SOCKS5, résolution DNS par le proxy
socks5h://identifiant:motdepasse@hote.exemple:8080

Le préfixe désigne le protocole du proxy, pas celui du site. Un proxy HTTP transporte très bien le HTTPS : votre outil lui demande d'ouvrir un tunnel (méthode CONNECT) et le chiffrement se négocie directement avec le site. Gardez donc http://, même pour des pages en https://. Pour choisir entre les deux protocoles, voyez notre comparatif proxy HTTP ou SOCKS5.

cURL : valider un accès en une ligne

Le service api.ipify.org, utilisé dans tous les exemples, renvoie l'IP qui l'a contacté : vous devez y lire celle du proxy, pas la vôtre.

# Proxy HTTP, identifiants dans l'adresse
curl -x "http://identifiant:motdepasse@hote.exemple:8080" https://api.ipify.org

# Même chose, identifiants passés à part avec -U
curl -x "http://hote.exemple:8080" -U "identifiant:motdepasse" https://api.ipify.org

# SOCKS5, le proxy résout les noms de domaine
curl --socks5-hostname hote.exemple:8080 -U "identifiant:motdepasse" https://api.ipify.org

# Équivalent avec une seule adresse
curl -x "socks5h://identifiant:motdepasse@hote.exemple:8080" https://api.ipify.org

--socks5-hostname, comme le préfixe socks5h://, confie la résolution des noms de domaine au proxy, ce que ne font pas --socks5 et socks5://. Sous Windows PowerShell, tapez curl.exe : curl y désigne une autre commande.

Python : requests et httpx

requests

La bibliothèque requests attend un dictionnaire qui associe un proxy à chaque type d'adresse visitée :

import requests

proxy = "http://identifiant:motdepasse@hote.exemple:8080"
proxies = {"http": proxy, "https": proxy}

r = requests.get("https://api.ipify.org", proxies=proxies, timeout=10)
print(r.text)  # doit afficher l'IP du proxy

Piège classique : la clé "https" désigne les sites en https://, pas le protocole du proxy, dont l'adresse reste en http://. Et sans timeout, requests peut attendre indéfiniment.

Pour le SOCKS5, installez la dépendance optionnelle et changez le préfixe :

pip install "requests[socks]"

proxy = "socks5h://identifiant:motdepasse@hote.exemple:8080"
proxies = {"http": proxy, "https": proxy}

Avec socks5://, requests résoudrait les noms sur votre machine : c'est une fuite DNS, que notre guide pour tester un proxy vous apprend à détecter.

httpx

Avec httpx, le proxy se règle au niveau du client, par le paramètre proxy. L'ancien paramètre proxies a disparu en version 0.28, ce qui casse de nombreux exemples publiés en ligne.

import httpx

proxy = "http://identifiant:motdepasse@hote.exemple:8080"

with httpx.Client(proxy=proxy, timeout=10.0) as client:
    r = client.get("https://api.ipify.org")
    print(r.text)

httpx.AsyncClient accepte le même paramètre. Pour le SOCKS5, installez httpx[socks] et passez une adresse en socks5://. Par défaut, httpx abandonne après cinq secondes d'inactivité réseau : adaptez ce délai aux sites visés.

Node.js : fetch, axios et SOCKS5

Les exemples suivants sont des modules ES (fichier .mjs ou "type": "module" dans package.json), ce qui autorise await au premier niveau.

fetch natif avec undici

Le fetch intégré à Node.js depuis la version 18 ne passe par aucun proxy par défaut, même si HTTPS_PROXY est définie. Il repose sur undici : installez ce paquet et passez un ProxyAgent dans l'option dispatcher.

npm install undici

import { ProxyAgent } from 'undici';

const dispatcher = new ProxyAgent('http://identifiant:motdepasse@hote.exemple:8080');

const res = await fetch('https://api.ipify.org?format=json', {
  dispatcher,
  signal: AbortSignal.timeout(10000), // abandon après 10 secondes
});
const { ip } = await res.json();
console.log(ip);

Créez l'agent une fois et réutilisez-le. Pour éviter tout écart de version avec le fetch intégré, vous pouvez aussi importer fetch depuis undici.

axios avec https-proxy-agent

npm install axios https-proxy-agent

import axios from 'axios';
import { HttpsProxyAgent } from 'https-proxy-agent';

const agent = new HttpsProxyAgent('http://identifiant:motdepasse@hote.exemple:8080');

const client = axios.create({
  httpsAgent: agent,
  proxy: false, // désactive la gestion de proxy intégrée d'axios
  timeout: 10000,
});

const { data } = await client.get('https://api.ipify.org?format=json');
console.log(data.ip);

proxy: false évite un conflit : axios lit lui-même les variables d'environnement de proxy, et ce réglage pourrait prendre le pas sur votre agent. HttpsProxyAgent couvre les sites en https:// ; pour du http://, le paquet http-proxy-agent joue le même rôle via httpAgent.

SOCKS5 avec socks-proxy-agent

npm install socks-proxy-agent

import axios from 'axios';
import { SocksProxyAgent } from 'socks-proxy-agent';

const agent = new SocksProxyAgent('socks5h://identifiant:motdepasse@hote.exemple:8080');

const { data } = await axios.get('https://api.ipify.org?format=json', {
  httpAgent: agent,
  httpsAgent: agent,
  proxy: false,
  timeout: 10000,
});
console.log(data.ip);

Cet agent sert aussi aux modules http et https de Node.js (option agent), mais pas au fetch natif.

Bonnes pratiques en production

Aucun mot de passe dans le code

Un identifiant écrit en dur finit tôt ou tard dans un dépôt Git ou sur une capture d'écran. Placez l'adresse du proxy dans une variable d'environnement, alimentée par un fichier .env exclu du dépôt ou par un gestionnaire de secrets. Les variables standard HTTPS_PROXY et HTTP_PROXY sont lues d'office par requests et httpx ; cURL les lit aussi, mais seulement en minuscules (http_proxy) pour la seconde :

export HTTPS_PROXY="http://identifiant:motdepasse@hote.exemple:8080"
export http_proxy="$HTTPS_PROXY"

curl https://api.ipify.org
python script.py  # requests et httpx utilisent aussi ces variables

Ces variables s'appliquent à tous les programmes lancés depuis ce terminal, pip et git compris. Sous PowerShell, écrivez $env:HTTPS_PROXY = "...". En Node.js, passez la valeur à l'agent : new ProxyAgent(process.env.HTTPS_PROXY).

Encoder les caractères spéciaux

Dans une URL, @, :, /, #, ? et % ont un rôle précis. Présents dans l'identifiant ou le mot de passe, ils faussent le découpage de l'adresse et l'authentification échoue. Encodez ces deux champs (@ devient %40). Cette fonction convertit une ligne au format Airproxy en adresse prête à l'emploi :

from urllib.parse import quote

def proxy_url(ligne, schema="http"):
    hote, port, identifiant, motdepasse = ligne.strip().split(":", 3)
    return f"{schema}://{quote(identifiant, safe='')}:{quote(motdepasse, safe='')}@{hote}:{port}"

print(proxy_url("hote.exemple:8080:identifiant:motdepasse"))
print(proxy_url("hote.exemple:8080:identifiant:motdepasse", "socks5h"))

En JavaScript, encodeURIComponent() joue le même rôle.

Délais d'attente et reprises

Ni requests ni axios n'imposent de délai par défaut : un proxy ou un site muet peut bloquer votre script. Fixez un délai sur chaque requête et ajoutez quelques reprises espacées pour absorber les erreurs passagères :

import os
import requests
from requests.adapters import HTTPAdapter
from urllib3.util import Retry

proxy = os.environ["HTTPS_PROXY"]
proxies = {"http": proxy, "https": proxy}

reprises = Retry(total=3, backoff_factor=1, status_forcelist=[429, 500, 502, 503, 504])
adaptateur = HTTPAdapter(max_retries=reprises)

session = requests.Session()
session.mount("http://", adaptateur)
session.mount("https://", adaptateur)

r = session.get("https://api.ipify.org", proxies=proxies, timeout=(5, 30))
print(r.text)

Le couple (5, 30) sépare le délai de connexion et celui de lecture, en secondes. Les reprises s'espacent de plus en plus et respectent l'en-tête Retry-After d'une réponse 429. Avec cURL, l'équivalent est --connect-timeout 10 --max-time 30 --retry 3.

Une session par proxy

Gardez un client par proxy (requests.Session, httpx.Client, ProxyAgent ou instance axios) : les connexions sont réutilisées et les identités restent séparées, car les cookies d'un compte ne doivent jamais passer par l'IP d'un autre. Pour une collecte, respectez les conditions d'utilisation des sites, leur robots.txt et le RGPD ; notre guide des proxies pour le web scraping explique comment répartir la charge.

Dépannage : 407, délais dépassés, certificats

Erreur 407 Proxy Authentication Required

Le proxy n'a pas reçu d'identifiants valides. Vérifiez qu'ils sont copiés sans espace ni retour à la ligne, que les caractères spéciaux sont encodés, qu'ils figurent bien dans l'adresse ou l'option utilisée, et que l'accès est actif dans votre espace client. En SOCKS5, le client signale un refus d'authentification plutôt qu'un code 407. curl -v montre l'étape qui échoue.

Délais dépassés

Un délai de connexion dépassé signale le plus souvent un proxy injoignable : hôte ou port erroné, ou pare-feu qui bloque ce port en sortie, fréquent en entreprise. Un délai de lecture dépassé indique plutôt un site lent ou trop de requêtes simultanées. Contrôlez l'accès avec notre testeur de proxy : s'il répond normalement, le problème est ailleurs.

Erreurs de certificat

Dans le tunnel d'un proxy HTTP, le chiffrement va de bout en bout : votre outil reçoit le certificat du site, pas celui du proxy. Une erreur de certificat vient donc d'ailleurs :

• une adresse de proxy en https:// : l'outil tente une connexion chiffrée vers le proxy, qui attend du HTTP simple (erreur SSL, souvent « wrong version number »). Passez à http:// ;
• une inspection TLS par un antivirus ou un pare-feu d'entreprise : déclarez son certificat racine (--cacert pour cURL, paramètre verify de requests, variable NODE_EXTRA_CA_CERTS pour Node.js).

Ne désactivez jamais la vérification (-k, verify=False) en production : vos échanges deviendraient interceptables.

Les proxies ISP dédiés d'Airproxy (France, Espagne, offre EU) sont livrés au format hôte:port:identifiant:mot de passe et répondent en HTTP(S) comme en SOCKS5 sur le même hôte et le même port : ces exemples s'appliquent tels quels. Pour un navigateur ou un logiciel, suivez plutôt notre guide pour configurer un proxy. Les localisations disponibles sont sur la page des offres.