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_proxy setting 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.