How to Use a Proxy with curl, Python and Node.js
· 6 min read
Most tools and libraries take a proxy as a single address, and once you know its format, setting one up takes a line or two. The examples below send a request to an IP lookup service, which answers with the address it sees, so you can confirm the traffic goes through the proxy.
Throughout, replace USER, PASS, HOST and PORT with your own details.
The proxy address
Nearly everything accepts the same format:
scheme://USER:PASS@HOST:PORT http://for an HTTP proxy, which also tunnels HTTPS.socks5h://for SOCKS5 with DNS resolved by the proxy.socks5://for SOCKS5 with DNS resolved on your machine, which is rarely what you want. The difference is explained in HTTP vs SOCKS5 proxies.
If you authenticate with an IP allowlist instead of a password, leave out USER:PASS@.
curl
Pass the proxy with -x:
curl -x http://USER:PASS@HOST:PORT https://ipinfo.io/json Or over SOCKS5:
curl -x socks5h://USER:PASS@HOST:PORT https://ipinfo.io/json curl also reads the proxy from environment variables, which many other command line tools respect too:
export https_proxy=http://USER:PASS@HOST:PORT
curl https://ipinfo.io/json One detail catches people out: for plain HTTP, curl only reads the lowercase http_proxy, not HTTP_PROXY. Use no_proxy to list hosts that
should be reached directly.
Python
requests
import requests
proxy = "http://USER:PASS@HOST:PORT"
proxies = {"http": proxy, "https": proxy}
response = requests.get("https://ipinfo.io/json", proxies=proxies, timeout=30)
print(response.json()) The dictionary maps the scheme of the address you visit to the proxy used for it, so both
entries point to the same proxy. Leaving out "https" is a common mistake: HTTPS
requests then go out directly, with no error to warn you.
For SOCKS5, install the optional dependency with pip install "requests[socks]" and
change the scheme:
proxy = "socks5h://USER:PASS@HOST:PORT"
proxies = {"http": proxy, "https": proxy} httpx
httpx takes a single proxy for the whole client. Reusing one client across requests also keeps connections open between them, which makes a noticeable difference through a proxy:
import httpx
with httpx.Client(proxy="http://USER:PASS@HOST:PORT", timeout=30) as client:
for _ in range(3):
print(client.get("https://ipinfo.io/json").json()["ip"]) For SOCKS5, install httpx[socks] and use a socks5h:// address.
Node.js
fetch with undici
Node's built-in fetch is powered by undici, which provides a proxy agent of its own.
Install the undici package and pass the agent as the dispatcher:
import { fetch, ProxyAgent } from "undici";
const dispatcher = new ProxyAgent("http://USER:PASS@HOST:PORT");
const response = await fetch("https://ipinfo.io/json", { dispatcher });
console.log(await response.json()); SOCKS5
For SOCKS5, the socks-proxy-agent package works with Node's own http and https modules, and with libraries built on them such as axios:
import https from "node:https";
import { SocksProxyAgent } from "socks-proxy-agent";
const agent = new SocksProxyAgent("socks5h://USER:PASS@HOST:PORT");
https.get("https://ipinfo.io/json", { agent }, (response) => {
response.pipe(process.stdout);
}); When it doesn't work
- 407 Proxy Authentication Required means the username or password was wrong, or never sent. Check for typos and for characters that need encoding.
- Special characters in the password. Characters such as
@,:or/break the address and have to be percent-encoded:
from urllib.parse import quote
password = quote("p@ss:word/1", safe="") # p%40ss%3Aword%2F1 - Connection refused or reset before anything is sent usually means the wrong port, or that your IP isn't on the proxy's allowlist.
- The lookup shows your own IP. The proxy isn't being used for that request: check
that it is set for HTTPS as well as HTTP, and that no
no_proxysetting matches the host. - Timeouts. Always set one. Without it, a single stalled connection can hang a job indefinitely.
Once requests go through, the other checks worth running, from DNS leaks to the fraud score, are in how to test a proxy.
With Leastslow
Every Leastslow IP takes HTTP and SOCKS5 on the same port, so the examples above work with the same host, port and credentials whichever scheme you use. Pricing is on the homepage.