cURL gira su un numero stimato di 20 miliardi di installazioni in tutto il mondo — è integrato di default in macOS, nella maggior parte delle distribuzioni Linux e in Windows 10/11. Eppure, chiedi a dieci sviluppatori come instradare correttamente una richiesta cURL tramite un proxy e otterrai dieci risposte leggermente diverse, metà delle quali smettono di funzionare appena entrano in gioco autenticazione o SOCKS.
È proprio questo il divario che voglio colmare qui. La maggior parte delle guide ti mostra un comando, ti dice che funziona e passa oltre. Non ti spiega come verificare che il proxy stia davvero facendo qualcosa (spoiler: a volte non lo fa), e di sicuro non ti accompagna attraverso i codici di errore che compaiono nel momento esatto in cui la tua configurazione si discosta anche di poco dal percorso “ideale”. Questa guida copre l’intero panorama — proxy HTTP/HTTPS, SOCKS4/SOCKS5/socks5h, variabili d’ambiente (con tutte le loro insidie specifiche), una tabella di troubleshooting seria e cosa fare quando cURL e un proxy semplicemente non bastano più.
Che cos’è cURL e perché usarlo con un proxy?
cURL è uno strumento da riga di comando per trasferire dati da e verso un URL. Tutto qui: niente interfaccia grafica, niente fronzoli, solo un programma che parla HTTP, HTTPS, FTP e altri protocolli. Il comando più semplice possibile è:
curl https://example.com
Questo recupera la pagina e stampa l’HTML grezzo nel terminale. Utile già da solo, ma il vero motivo per cui sviluppatori e utenti business più tecnici usano cURL è testare API, raccogliere dati, verificare contenuti con restrizioni geografiche ed eseguire richieste all’interno di pipeline CI/CD.
Un proxy si colloca tra la tua macchina e il server di destinazione, inoltrando la richiesta per tuo conto. Il server di destinazione vede l’IP del proxy, non il tuo. Questo conta per diverse ragioni legittime: verificare come appare il tuo sito da un altro Paese, aggirare limiti di frequenza durante i test QA o instradare il traffico attraverso il gateway aziendale richiesto dalla tua organizzazione. cURL supporta l’intera gamma di protocolli proxy — HTTP, HTTPS, SOCKS4 e SOCKS5 — e i flag che ritroverai più volte in questa guida sono -x / --proxy (l’indirizzo del proxy), -v (output dettagliato, il tuo migliore alleato nel debug) e -k (salta la verifica SSL, da usare praticamente mai fuori dai test).
Una nota veloce prima di proseguire: questa guida riguarda il funzionamento di rete dell’uso di un proxy con cURL. Non è un permesso a ignorare i termini di servizio di un sito o le policy di sicurezza della tua organizzazione. Un proxy cambia il percorso di rete — non cambia ciò che è legale o consentito.
Prima di iniziare
Difficoltà: Da principiante a intermedio
Tempo richiesto: circa 15 minuti per seguire gli esempi principali
Cosa ti serve:
- cURL installato (verifica con
curl --version— se sei su macOS, Linux o Windows 10/11, è quasi certamente già presente) - Credenziali proxy dal tuo provider: host, porta, protocollo (HTTP/HTTPS/SOCKS) e username/password se richiesti
- Un terminale (Terminal su macOS, qualsiasi shell su Linux, PowerShell o CMD su Windows)
Se per qualche motivo cURL non è installato, basta una riga: brew install curl su macOS tramite Homebrew, sudo apt install curl su Debian/Ubuntu, oppure sudo yum install curl su RHEL/CentOS. Su Windows è incluso nel sistema operativo a partire da Windows 10 build 17063.
In tutta la guida userò valori segnaposto — proxy.example:8080 per l’indirizzo del proxy e user:pwd per le credenziali. Sostituiscili con i dati reali del tuo proxy e non incollare mai credenziali vere nella cronologia della shell, in uno screenshot o in un messaggio Slack. Ho visto trapelare più password proxy nei canali Slack di quante mi piaccia ammettere.
Come usare cURL con un proxy HTTP o HTTPS
Questa è la configurazione più comune, quella che userai per la grandissima maggioranza delle attività con proxy.
Usare il flag -x / --proxy
La sintassi di base è questa:
curl -x "http://user:pwd@proxy.example:8080" "https://httpbin.org/ip"
-x e --proxy fanno esattamente la stessa cosa — scegli pure quello che ti è più facile ricordare. Poiché HTTP è lo schema proxy predefinito di cURL, tecnicamente puoi anche togliere il prefisso http:// e scrivere solo proxy.example:8080. Io però lo scriverei comunque in modo esplicito: fra sei mesi ti ringrazierai per la chiarezza.
Racchiudi l’intero URL tra virgolette doppie. Se la password contiene @, # o &, una stringa non quotata verrà alterata dalla shell prima ancora che cURL la legga.
Connessione tramite un proxy HTTPS
Alcuni provider cifrano la connessione verso il proxy stesso con TLS, non solo la connessione dal proxy al tuo target. È una cosa diversa dal fare scraping di un sito HTTPS — il protocollo del proxy e quello della destinazione sono variabili indipendenti. Per specificarlo:
curl -x "https://user:pwd@proxy.example:8080" "https://httpbin.org/ip"
Se qui ricevi un errore di certificato, resisti alla tentazione di aggiungere -k e andare avanti. Quel flag disattiva del tutto la verifica del certificato SSL, cosa accettabile per un test locale di cinque minuti e una pessima idea per qualsiasi cosa tocchi produzione o dati reali degli utenti. Se stai lavorando con un proxy aziendale che intercetta TLS (una configurazione MITM, comune in ambito enterprise), la correzione giusta è importare il certificato CA del proxy, non disattivare la verifica.
Autenticazione con --proxy-user
Puoi anche separare le credenziali e metterle in un flag dedicato invece di inserirle nell’URL:
curl -x "http://proxy.example:8080" --proxy-user "user:pwd" "https://httpbin.org/ip"
Nota che il -U maiuscolo non è la stessa cosa dell’autenticazione verso il sito di destinazione (-u / --user, minuscolo) — confonderli è un modo facile per inviare la password del proxy alla destinazione sbagliata. Negli ambienti aziendali che usano NTLM o Digest invece di Basic, aggiungi --proxy-ntlm o --proxy-digest insieme a --proxy-user.
Come usare cURL con un proxy SOCKS: SOCKS4 vs. SOCKS5 vs. socks5h
I proxy SOCKS operano a un livello più basso rispetto ai proxy HTTP — non si curano del protocollo che stai inoltrando, ed è proprio questo a renderli utili per traffico non HTTP, circuiti Tor e tutto ciò che è sensibile alla privacy. Molte guide concorrenti riducono tutto a un singolo comando e basta. È un errore, perché le differenze tra SOCKS4, SOCKS5 e socks5h:// contano davvero.
| Funzione | SOCKS4 | SOCKS5 | socks5h:// |
|---|---|---|---|
| Supporto TCP | Sì | Sì | Sì |
| Supporto UDP | No | Sì | Sì |
| Autenticazione | No | Sì | Sì |
| Risoluzione DNS remota | No | No (DNS locale) | Sì (il proxy risolve) |
| Compatibile con Tor | No | Rischioso (leak DNS) | Sì |
La riga sulla risoluzione DNS è quella su cui le persone si fanno davvero male. Con socks5://, la tua macchina risolve l’hostname prima di passare la connessione al proxy — il che significa che il tuo resolver DNS locale (e di conseguenza il tuo ISP) vede esattamente quale dominio stai cercando di raggiungere, anche se il traffico HTTP vero e proprio passa nel proxy. socks5h:// risolve il problema facendo eseguire la risoluzione al proxy, così nulla della destinazione trapela localmente. È questo il motivo per cui la documentazione di Tor insiste su socks5h:// — usare il semplice socks5:// vanifica gran parte dell’anonimato che Tor dovrebbe garantire.
Ecco ciascuna variante in 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"
A meno che tu non abbia un motivo preciso per non farlo, scegli socks5h:// come impostazione predefinita. Non costa nulla in più e chiude una fuga di informazioni che altrimenti potresti non notare mai.
Impostare il proxy con le variabili d’ambiente (ed evitare le trappole)
Impostare -x su ogni singolo comando diventa presto noioso. Le variabili d’ambiente ti permettono di definire il proxy una volta per sessione di shell e fare in modo che tutte le chiamate cURL successive lo ereditino automaticamente — il manuale di cURL documenta http_proxy, HTTPS_PROXY, ALL_PROXY e NO_PROXY come insieme supportato.
Le basi
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"
Ecco il punto che confonde tutti: il nome della variabile si riferisce al protocollo dell’URL di destinazione, non a quello del proxy. Quindi http_proxy governa le richieste verso URL http://, e HTTPS_PROXY governa le richieste verso URL https:// — puoi puntare entrambe allo stesso identico server proxy HTTP, ed è assolutamente normale.
Escludere con NO_PROXY
export NO_PROXY="localhost,127.0.0.1,.internal.example"
Separato da virgole, e il punto iniziale in .internal.example funziona come wildcard per qualsiasi sottodominio. NO_PROXY ha la precedenza su tutto il resto — anche se -x è impostato esplicitamente nella riga di comando, una corrispondenza in NO_PROXY farà bypassare il proxy a quella richiesta.
Le trappole in cui le persone cadono davvero
- Dimenticare
export. Se scrivi solohttp_proxy=http://...senzaexport, la variabile resta visibile solo nella shell corrente ed è completamente invisibile a cURL come processo figlio. Per esperienza, è la causa più comune dei ticket “il proxy non funziona”. - Sensibilità alle maiuscole/minuscole. cURL controlla specificamente prima
http_proxyin minuscolo e le dà priorità se esistono entrambe le varianti. Alcuni altri strumenti leggono solo la versione maiuscola. Se stai cercando di capire perché una variabile “non viene presa”, controlla se ne esiste una duplicata con casing diverso. - La trappola dell’alias in PowerShell. In PowerShell 5.1, digitare
curlnon esegue affatto cURL — richiamaInvoke-WebRequest, uno strumento completamente diverso con flag diversi. Se il tuo-xgenera errori strani su Windows, digita esplicitamentecurl.exeper assicurarti di stare davvero usando cURL. - Differenze di sintassi su Windows. CMD usa
set http_proxy=...; PowerShell usa$env:http_proxy = "...". Confonderle tra una sessione di terminale e l’altra è un modo semplice per perdere un pomeriggio. - Variabili vecchie.
unset http_proxyeunset https_proxycancellano una configurazione proxy obsoleta che sta instradando — e facendo fallire — ogni richiesta in silenzio.
Per passare rapidamente da una configurazione all’altra, un paio di alias nel tuo .bashrc fanno risparmiare tempo reale:
alias proxyon='export http_proxy="http://proxy.example:8080"; export https_proxy="http://proxy.example:8080"'
alias proxyoff='unset http_proxy; unset https_proxy'
Fare in modo che cURL usi sempre un proxy (file di configurazione)
Se per il 95% del tempo lavori dietro un proxy aziendale, un file .curlrc (su sistemi Unix-like, nella tua home) o _curlrc (su Windows, nella cartella app-data) imposta un default persistente senza toccare affatto le variabili d’ambiente:
proxy="http://proxy.example:8080"
Per qualsiasi richiesta occasionale in cui vuoi escluderlo, --noproxy "*" sovrascrive la configurazione per quella singola esecuzione. In generale la precedenza è flag da riga di comando > variabile d’ambiente > file di configurazione, quindi -x sulla riga di comando vince sempre in caso di conflitto.
Un’avvertenza importante: non mettere una password in chiaro dentro .curlrc se il file può essere sincronizzato, sottoposto a backup o finire accidentalmente in un repository. Per le pipeline CI, usa invece il secret manager della tua piattaforma e inietta le credenziali come variabili d’ambiente mascherate.
Come verificare che il proxy stia davvero funzionando
Questa è la sezione che quasi tutte le altre guide saltano, ed è quella che fa risparmiare più tempo nel debug. Configurare un proxy e dare per scontato che stia instradando il traffico è il modo migliore per passare ore a cercare di risolvere un problema in uno scraper che in realtà non ha mai usato il proxy.
Metodo 1: confronta il tuo IP in uscita
Esegui la stessa richiesta che restituisce l’IP due volte — una diretta, una tramite proxy — e confronta:
curl https://httpbin.org/ip
curl -x "http://user:pwd@proxy.example:8080" https://httpbin.org/ip
Se entrambi i comandi restituiscono lo stesso indirizzo IP, il proxy non sta facendo nulla. Controlla la sintassi del flag, le variabili d’ambiente o se NO_PROXY sta accidentalmente corrispondendo alla tua destinazione.
Metodo 2: leggi l’output verbose
Aggiungi -v a qualsiasi richiesta via proxy e cURL stamperà l’intero handshake:
curl -v -x "http://user:pwd@proxy.example:8080" https://httpbin.org/ip
Cerca una riga come * Connected to proxy.example (xx.xx.xx.xx) port 8080, seguita da > CONNECT httpbin.org:443 HTTP/1.1 e infine < HTTP/1.1 200 Connection established. Questa sequenza — connessione al proxy, poi tunnel CONNECT verso la destinazione — è il metodo HTTP CONNECT in azione, ed è esattamente ciò che deve accadere quando una destinazione HTTPS viene instradata attraverso un proxy HTTP. Se la riga CONNECT non compare mai, il flag del proxy non viene applicato. Un avviso importante: usa -v solo mentre stai facendo debug attivo e oscura l’output prima di condividerlo ovunque — la modalità verbose può stampare le credenziali del proxy in chiaro.
Metodo 3: confronto affiancato
Per i test geografici, salva entrambi gli output in file e confrontali con 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
Se il corpo della risposta (o gli header, nel caso di contenuti con restrizioni geografiche) cambia, hai una conferma visiva che il proxy sta davvero modificando il tuo percorso di rete — un modo rapido e a basso costo per togliersi ogni dubbio prima di scavare oltre.
Risolvere gli errori proxy più comuni di cURL
La maggior parte delle guide sorvola su questa parte e cita -k una volta sola. L’argomento merita una vera tabella di riferimento.
| Errore | Causa probabile | Soluzione |
|---|---|---|
curl: (7) Failed to connect | Host/porta del proxy errati, oppure proxy non disponibile | Verifica l’indirizzo; prova la connettività grezza con telnet host port o nc -zv host port |
407 Proxy Authentication Required | Credenziali proxy mancanti o errate | Aggiungi --proxy-user user:pass; verifica se il provider richiede NTLM/Digest/Negotiate invece di Basic |
curl: (56) Recv failure: Connection reset by peer | Il proxy ha interrotto la connessione a metà trasferimento | Controlla la stabilità del proxy con il provider; se è un proxy che termina TLS, verifica la gestione dei certificati invece di disattivarla forzatamente |
curl: (28) Connection timed out | Firewall che blocca, proxy obsoleto o porta sbagliata | Esegui env | grep -i proxy per cercare variabili residue; rimuovi quelle vecchie; prova una richiesta diretta per isolare la causa |
| Errore di verifica del certificato | Certificato del proxy non attendibile o che intercetta il traffico | Recupera la catena CA corretta e usa --proxy-cacert; evita di disattivare la verifica fuori da una diagnosi una tantum |
La prima mossa universale per ognuno di questi casi è aggiungere -v. Ti dice esattamente dove si interrompe la connessione — risoluzione DNS, connessione TCP, handshake TLS o scambio di autenticazione con il proxy — invece di lasciarti indovinare in base a un codice di errore di tre cifre.
Per i proxy aziendali in particolare, --proxy-ntlm e --proxy-negotiate coprono gli schemi di autenticazione dei domini Windows. Una cosa che cURL davvero non gestisce in modo nativo: i file PAC (Proxy Auto-Config, gli script che alcune aziende usano per assegnare dinamicamente i proxy). Se la tua azienda ne usa uno, dovrai estrarre manualmente l’host e la porta effettivi del proxy — di solito dalle impostazioni di rete del browser — perché cURL non ha un parser PAC integrato.
Quando cURL + un proxy non basta
cURL con un proxy gestisce HTML statico, chiamate API REST e semplici recuperi di dati con un’efficacia difficilmente eguagliabile. Dove inizia a cedere è davanti alle difese più comuni del web moderno: applicazioni single-page renderizzate in JavaScript, sistemi anti-bot come Cloudflare o Akamai e muri CAPTCHA. Punta cURL a una app React o Vue protetta da uno di questi sistemi e riceverai un <div id="root"></div> vuoto — tecnicamente una richiesta riuscita, praticamente dati inutili. Non è un bug di cURL. Semplicemente non è un browser, e non ha mai finto di esserlo.
Se sei già abituato a usare cURL dal terminale e arrivi a quel punto, il passo naturale successivo non è cambiare completamente strumento, ma aggiungere uno strato che gestisca rendering e struttura per te. È questo il vuoto che gli strumenti per sviluppatori di Thunderbit sono stati progettati per colmare.
| Scenario | cURL + Proxy | Thunderbit API (POST /extract) |
|---|---|---|
| Pagina HTML statica | Funziona perfettamente | Funziona, e restituisce anche dati strutturati |
| SPA renderizzata in JS | Restituisce HTML vuoto/parziale | renderMode: "full" gestisce il JS |
| Anti-bot / CAPTCHA | Bloccato | Gestione integrata |
| Output di dati strutturati | HTML grezzo — da analizzare manualmente | JSON tramite il tuo schema |
| Batch (100+ URL) | Loop manuale + rate limiting gestito da te | POST /batch/extract |
L’Open API di Thunderbit espone un endpoint /extract che restituisce JSON già allineato allo schema direttamente da pagine pesanti di JavaScript, e un endpoint /distill per la conversione pulita in Markdown — entrambi chiamabili dalla stessa sessione di terminale in cui hai sempre usato i comandi cURL. C’è anche un server MCP per assistenti di coding AI come Claude o Cursor, e una CLI (npx @thunderbit/thunderbit-cli extract <url> --schema fields.json) se preferisci restare completamente negli script. Nulla di tutto questo sostituisce cURL per i lavori in cui cURL eccelle — semplicemente prende il testimone dove cURL, strutturalmente, non può andare oltre. Se vuoi una visione più ampia di dove si colloca l’estrazione assistita da AI rispetto alla scrittura di una logica di scraping personalizzata, la nostra panoramica su AI web scraping e il confronto sui migliori AI web scraper approfondiscono l’argomento; il nostro articolo su web scraping senza codice è un ottimo punto di partenza se arrivi da un contesto business invece che ingegneristico.
Tirando le somme
Far dialogare correttamente cURL e un proxy non è difficile, una volta capito dove si trovano i veri punti di rottura — e, a quanto pare, quasi nessuno di essi è il proxy stesso. Dimenticare export. Confondere -u con -U. Usare socks5:// quando intendevi socks5h://. Eseguire l’alias curl di PowerShell invece di curl.exe. Ognuno di questi produce un errore confuso e generico che non ha nulla a che vedere con il provider del proxy.
L’abitudine che fa risparmiare più tempo: verifica prima di fare troubleshooting. Esegui il controllo dell’IP, dai un’occhiata all’output di -v, conferma che il proxy sia davvero nel percorso della richiesta prima di presumere che il problema sia a valle. E quando il target inizia a risponderti con JavaScript invece che con HTML pulito, non è un problema di cURL da risolvere con più flag — è il segnale che ti serve uno strumento pensato per il rendering, come Thunderbit API, che offre anche un piano gratuito se vuoi toccare con mano la differenza tra JSON in uscita e HTML grezzo.
FAQ
cURL usa un proxy di default?
No. A meno che tu non abbia impostato le variabili d’ambiente http_proxy / HTTPS_PROXY o configurato un file .curlrc, cURL si connette direttamente alla destinazione senza usare alcun proxy.
Come faccio a impedire a cURL di usare un proxy per una sola richiesta?
Aggiungi --noproxy "*" a quel comando specifico. Per disattivarlo per tutta la sessione di shell, esegui unset http_proxy && unset https_proxy.
Posso usare cURL con proxy rotanti?
Sì — se il tuo provider offre un gateway rotante (un singolo endpoint che assegna un IP nuovo a ogni richiesta), basta puntare -x a quell’indirizzo come faresti con qualsiasi altro proxy. Per logiche di rotazione più complesse su target renderizzati in JS, uno strato API come quello di Thunderbit gestisce internamente la rotazione e la parte anti-bot, così non devi scrivere a mano la logica di retry.
Perché socks5:// espone le mie richieste DNS mentre socks5h:// no?
Con socks5://, la tua macchina locale risolve l’hostname di destinazione prima di inviare la richiesta di connessione al proxy — il che significa che il resolver DNS del tuo ISP vede il dominio che stai visitando. socks5h:// sposta la risoluzione dell’hostname sul proxy stesso, così nulla della destinazione è visibile localmente.
È legale usare cURL con un proxy?
Usare un proxy è legale nella maggior parte delle giurisdizioni, di per sé. Quello che conta è cosa ne fai: rispetta sempre i termini di servizio del sito di destinazione, il robots.txt dove applicabile e qualsiasi normativa rilevante sulla privacy dei dati. Questa guida copre solo i meccanismi tecnici, non un via libera legale per qualunque caso d’uso.
Scopri di più
