socks5h vs socks5: Remote DNS in curl, Python and Node (With Code)
socks5h is the same SOCKS5 protocol as socks5, with one difference: in clients that follow this URL convention (curl, Python Requests, Node's socks-proxy-agent), the h means send the hostname to the proxy and let the proxy resolve DNS. With plain socks5://, your machine does the DNS lookup and sends the proxy only an IP address. If you want DNS for the target resolved on the proxy side, for example to keep target hostnames away from your local resolver or to reach names only the proxy can resolve, use socks5h://. For a SOCKS5 endpoint to point this at, our SOCKS5 ISP proxies start from $0.75/IP per month, dedicated and on US carrier ASNs.
Quick reference:
# Local DNS: your machine resolves example.com, the proxy gets an IP address
curl -x "socks5://USERNAME:PASSWORD@PROXY_HOST:PROXY_PORT" https://example.com
# Remote DNS: the proxy resolves example.com (these two lines do the same thing)
curl -x "socks5h://USERNAME:PASSWORD@PROXY_HOST:PROXY_PORT" https://example.com
curl --socks5-hostname PROXY_HOST:PROXY_PORT -U USERNAME:PASSWORD https://example.comWhat socks5h means
SOCKS5 (RFC 1928) lets a client tell the proxy where to connect in one of three forms: an IPv4 address, an IPv6 address, or a domain name. The h suffix is not a separate protocol; it is a client-side convention, used by curl, Python Requests and Node's socks-proxy-agent, that picks the domain-name form.
| Proxy URL | Who resolves DNS | What the proxy receives | Typical result |
|---|---|---|---|
socks5:// | Your machine (local resolver) | An IP address | The lookup for the target goes through your local resolver; the proxy cannot change a wrong or blocked answer |
socks5h:// | The proxy | The hostname, e.g. example.com | The lookup for the target happens on the proxy side, with the proxy's resolver |
socks4:// | Your machine | IPv4 only | No IPv6, no auth beyond a user ID |
socks4a:// | The proxy | The hostname | The SOCKS4 version of the same idea |
Rule of thumb: when in doubt, use socks5h://. The only time plain socks5:// is the better choice is when you deliberately want your own resolver's answer (for example, a hosts-file entry or split DNS on your machine).
When remote DNS matters
Keeping target hostnames off your local resolver. With
socks5://, each target hostname is looked up by your machine's resolver (often your ISP's or your company's), even though the traffic itself goes through the proxy. Withsocks5h://the client skips that lookup for proxied requests. Other apps on the machine still use your normal DNS. See DNS leak for the wider picture.Answers from the proxy's side. Large sites and CDNs often answer DNS based on where the resolver is. With
socks5h://the target name is resolved by the proxy's resolver, which for most providers sits near the proxy, so the edge you get usually fits the exit location better.Hostnames only the proxy can resolve. Internal names behind a jump host,
.onionaddresses through a Tor SOCKS port, or names your local resolver blocks fail withsocks5://and work withsocks5h://. The demo below shows exactly this.Fewer mismatched signals. If the exit IP is in New York but the target lookups come from your home network, the two point in different directions. Remote DNS removes that one mismatch.
Neither scheme encrypts anything (SOCKS5 itself adds no encryption; use HTTPS URLs for that), and with the same endpoint both leave through the same exit IP.
We ran it: socks5 vs socks5h side by side
To show the difference with real output, we ran a tiny SOCKS5 server on localhost on 12 Nov 2026. It accepts USERNAME/PASSWORD, logs which address type each client sends, and has one custom name mapping, internal.test -> 127.0.0.1, that no public DNS server knows. Client versions: curl 7.68.0, Python 3.8 with requests 2.22.0 + PySocks 1.7.1, Node.js v24.22.1 with socks-proxy-agent 10.1.0.
To reproduce it, save this as s5server.py (Python 3 standard library only; a demo, not a production proxy):
import select
import socket
import struct
import threading
USER, PASS = b"USERNAME", b"PASSWORD"
LOCAL_DNS = {"internal.test": "127.0.0.1"} # a name only this proxy can resolve
def recvn(c, n):
b = b""
while len(b) < n:
x = c.recv(n - len(b))
if not x:
raise EOFError
b += x
return b
def handle(c):
try:
_, nmethods = recvn(c, 2)
recvn(c, nmethods)
c.sendall(b"\x05\x02") # username/password auth (RFC 1929)
recvn(c, 1)
user = recvn(c, recvn(c, 1)[0])
password = recvn(c, recvn(c, 1)[0])
if (user, password) != (USER, PASS):
c.sendall(b"\x01\x01")
return
c.sendall(b"\x01\x00")
_, cmd, _, atyp = recvn(c, 4)
if atyp == 1:
host, kind = socket.inet_ntoa(recvn(c, 4)), "IPv4 address (client resolved DNS)"
elif atyp == 3:
host, kind = recvn(c, recvn(c, 1)[0]).decode(), "hostname (proxy resolves DNS)"
else:
host, kind = socket.inet_ntop(socket.AF_INET6, recvn(c, 16)), "IPv6 address (client resolved DNS)"
port = struct.unpack(">H", recvn(c, 2))[0]
print(f"proxy got {kind}: {host}:{port}", flush=True)
remote = socket.create_connection((LOCAL_DNS.get(host, host), port), timeout=5)
c.sendall(b"\x05\x00\x00\x01" + socket.inet_aton("0.0.0.0") + b"\x00\x00")
while True:
ready, _, _ = select.select([c, remote], [], [], 10)
if not ready:
break
for sock in ready:
data = sock.recv(65536)
if not data:
return
(remote if sock is c else c).sendall(data)
except EOFError:
pass
except Exception as e:
print("error", e, flush=True)
finally:
c.close()
srv = socket.socket()
srv.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
srv.bind(("127.0.0.1", 1080))
srv.listen(16)
while True:
conn, _ = srv.accept()
threading.Thread(target=handle, args=(conn,), daemon=True).start()Then start it and a test web server in two terminals:
# terminal 1: a web server on port 8080 that serves one file
mkdir -p www && echo "hello from internal.test" > www/index.txt
python3 -m http.server 8080 --bind :: --directory www
# terminal 2: the demo SOCKS5 proxy on 127.0.0.1:1080
python3 -u s5server.pycurl, verbose, same URL with both schemes (--noproxy "" makes sure curl does not skip the proxy for localhost):
curl -sSv --noproxy "" -x "socks5://USERNAME:[email protected]:1080" http://localhost:8080/index.txt
curl -sSv --noproxy "" -x "socks5h://USERNAME:[email protected]:1080" http://localhost:8080/index.txtOutput (excerpt, filtered to the SOCKS lines and the body):
* SOCKS5 connect to IPv6 ::1:8080 (locally resolved)
hello from internal.test
* SOCKS5 connect to localhost:8080 (remotely resolved)
hello from internal.testcurl says it outright: (locally resolved) vs (remotely resolved). That verbose line is the quickest check for any curl setup.
A name only the proxy can resolve:
curl -sS --noproxy "" -x "socks5://USERNAME:[email protected]:1080" http://internal.test:8080/index.txt
curl -sS --noproxy "" -x "socks5h://USERNAME:[email protected]:1080" http://internal.test:8080/index.txtcurl: (6) Could not resolve host: internal.test
hello from internal.testWhat the proxy logged (excerpt; it also prints a blank error line when a client closes a connection):
proxy got IPv6 address (client resolved DNS): ::1:8080
proxy got hostname (proxy resolves DNS): localhost:8080
proxy got hostname (proxy resolves DNS): internal.test:8080With socks5://, curl never sent a connect request for internal.test at all: the local lookup failed first, so the proxy log has no line for it.
curl
| Option | DNS | Notes |
|---|---|---|
-x socks5://... or --socks5 host:port | Local | -U user:pass for auth with --socks5 |
-x socks5h://... or --socks5-hostname host:port | Remote | Same flags, hostname sent to the proxy |
ALL_PROXY=socks5h://... env var | Remote | Picked up by curl and many other tools |
A complete check that prints the exit IP through remote DNS:
#!/usr/bin/env bash
set -euo pipefail
: "${USERNAME:?set USERNAME}" "${PASSWORD:?set PASSWORD}" "${PROXY_HOST:?set PROXY_HOST}" "${PROXY_PORT:?set PROXY_PORT}"
curl -sS --max-time 15 \
-x "socks5h://${USERNAME}:${PASSWORD}@${PROXY_HOST}:${PROXY_PORT}" \
https://api.ipify.org
echoIf your password contains @, : or /, URL-encode it (@ becomes %40) or use --socks5-hostname PROXY_HOST:PROXY_PORT -U 'USERNAME:PASSWORD' instead. More flags and examples are on our curl proxy page.
Python Requests
Requests speaks SOCKS through PySocks. Install the extra first:
pip install "requests[socks]"On PyPI on 12 Nov 2026 the current versions were requests 2.34.2 (needs Python 3.10+) and PySocks 1.7.1. Without PySocks, both schemes fail. Our run of the script below without PySocks installed:
socks5: failed -> InvalidSchema: Missing dependencies for SOCKS support.
socks5h: failed -> InvalidSchema: Missing dependencies for SOCKS support.A complete script that tries both schemes, so you can see the difference on your own proxy:
import os
from urllib.parse import quote
import requests
USERNAME = os.environ.get("USERNAME", "USERNAME")
PASSWORD = os.environ.get("PASSWORD", "PASSWORD")
PROXY_HOST = os.environ.get("PROXY_HOST", "PROXY_HOST")
PROXY_PORT = os.environ.get("PROXY_PORT", "PROXY_PORT")
URL = os.environ.get("TARGET_URL", "https://api.ipify.org")
auth = f"{quote(USERNAME, safe='')}:{quote(PASSWORD, safe='')}"
for scheme in ("socks5", "socks5h"):
proxy = f"{scheme}://{auth}@{PROXY_HOST}:{PROXY_PORT}"
try:
r = requests.get(URL, proxies={"http": proxy, "https": proxy}, timeout=15)
print(f"{scheme}: HTTP {r.status_code} -> {r.text.strip()}")
except requests.exceptions.RequestException as e:
print(f"{scheme}: failed -> {type(e).__name__}: {e}")Run it against the demo proxy with USERNAME=USERNAME PASSWORD=PASSWORD PROXY_HOST=127.0.0.1 PROXY_PORT=1080 TARGET_URL=http://internal.test:8080/index.txt python3 dns_check.py (for a real proxy, set your own values and leave out TARGET_URL). Output:
socks5: failed -> ConnectionError: SOCKSHTTPConnectionPool(host='internal.test', port=8080): Max retries exceeded with url: /index.txt (Caused by NewConnectionError('<urllib3.contrib.socks.SOCKSConnection object at 0x7f216f3540a0>: Failed to establish a new connection: [Errno -2] Name or service not known'))
socks5h: HTTP 200 -> hello from internal.testNote the error: Name or service not known comes from your local resolver (the username and password are URL-encoded in the script, so @ or : in a password is safe), which is the tell-tale sign that socks5:// did the lookup on your machine. Set both the http and https keys in proxies; if you set only http, HTTPS requests skip the proxy entirely. For sessions, retries and auth details, see our Python Requests proxy guide.
Node.js
Node's built-in http/https modules need an agent for SOCKS. socks-proxy-agent (10.1.0 on npm on 12 Nov 2026) reads the scheme from the URL: socks5:// resolves locally, socks5h:// sends the hostname to the proxy.
npm install socks-proxy-agentSave as dns-check.mjs:
import { SocksProxyAgent } from "socks-proxy-agent";
const { USERNAME = "USERNAME", PASSWORD = "PASSWORD", PROXY_HOST = "PROXY_HOST", PROXY_PORT = "PROXY_PORT" } = process.env;
const url = process.env.TARGET_URL ?? "https://api.ipify.org";
const http = url.startsWith("https:") ? await import("node:https") : await import("node:http");
const auth = `${encodeURIComponent(USERNAME)}:${encodeURIComponent(PASSWORD)}`;
function get(scheme) {
const agent = new SocksProxyAgent(`${scheme}://${auth}@${PROXY_HOST}:${PROXY_PORT}`);
return new Promise((resolve) => {
const req = http.get(url, { agent, signal: AbortSignal.timeout(15000) }, (res) => {
let body = "";
res.setEncoding("utf8");
res.on("data", (chunk) => (body += chunk));
res.on("end", () => resolve(`${scheme}: HTTP ${res.statusCode} -> ${body.trim()}`));
res.on("error", (e) => resolve(`${scheme}: failed -> ${e.code ?? ""} ${e.message}`));
});
req.on("error", (e) => resolve(`${scheme}: failed -> ${e.code ?? ""} ${e.message}`));
});
}
for (const scheme of ["socks5", "socks5h"]) {
console.log(await get(scheme));
}Run it with USERNAME=USERNAME PASSWORD=PASSWORD PROXY_HOST=127.0.0.1 PROXY_PORT=1080 TARGET_URL=http://internal.test:8080/index.txt node dns-check.mjs. AbortSignal.timeout(15000) cancels a request that stalls. Output against the demo proxy (Node v24.22.1):
socks5: failed -> ENOTFOUND getaddrinfo ENOTFOUND internal.test
socks5h: HTTP 200 -> hello from internal.testgetaddrinfo ENOTFOUND is again the local resolver failing, which shows socks5:// resolved on your side. Note that Node's built-in fetch does not take this kind of agent; use http/https with the agent as above, or a library that supports SOCKS.
Other tools at a glance
| Tool | Where DNS is resolved | Credentials |
|---|---|---|
| curl | socks5:// / --socks5: local. socks5h:// / --socks5-hostname: proxy | In the URL or -U |
| Python Requests (+ PySocks) | socks5://: local. socks5h://: proxy | In the URL |
Node socks-proxy-agent | socks5://: local. socks5h://: proxy | In the URL |
Chrome / Chromium (--proxy-server="socks5://PROXY_HOST:PROXY_PORT") | Always the proxy: Chromium's proxy docs say SOCKSv5 name resolution "is always done proxy side" | Chromium's docs say no SOCKSv5 authentication methods are supported |
| Python httpx | Install pip install "httpx[socks]" and pass proxy="socks5://..." (httpx docs); the docs don't state where DNS is resolved | In the URL |
For tools whose docs don't say where DNS is resolved, test it with the checks in the next section rather than assuming.
How to check where DNS is resolved on your setup
curl verbose: run with
-vand look for(remotely resolved)vs(locally resolved), as in the demo above. This is the clearest signal.Use a hostname your resolver can't answer, like the
internal.testmapping above: it only works if the proxy does the lookup.Watch your own DNS traffic as a hint: on Linux or macOS,
sudo tcpdump -n -i any port 53in a second terminal. A query for the target name while you usesocks5h://means something resolved locally; no query is not proof on its own, because caching, the hosts file or encrypted DNS can also hide it.Check the exit IP from the same client: request
https://api.ipify.orgthrough the proxy in the same script (the defaultTARGET_URLabove does this). To confirm a proxy is up and see its location, use our proxy checker; what is my IP shows the IP of the browser you open it in.
Common errors and fixes
| Error | Where | Likely cause | Fix |
|---|---|---|---|
InvalidSchema: Missing dependencies for SOCKS support. | Python Requests | PySocks not installed in this environment | pip install "requests[socks]" in the same environment that runs the script |
SOCKSHTTPConnectionPool ... Name or service not known (or SOCKSHTTPSConnectionPool for HTTPS) | Python Requests | socks5:// resolved locally and the name failed | Switch to socks5h:// |
curl: (6) Could not resolve host | curl | Local DNS lookup failed with --socks5 / socks5:// | Use socks5h:// or --socks5-hostname |
getaddrinfo ENOTFOUND | Node.js | Local lookup with a socks5:// agent | Use a socks5h:// agent URL |
Failed to receive SOCKS5 connect request ack | curl | The proxy refused or could not complete the connect (target down, port closed, or the proxy dropped the request) | Check the target host and port, then the proxy |
407 Proxy Authentication Required | Any | This is an HTTP-proxy response, so you are talking to an HTTP proxy port or using an http:// proxy URL, with wrong or missing credentials | Fix the credentials, or switch the plan to SOCKS5 and use socks5h:// (see SOCKS5 proxy setup) |
Using socks5h with CleanProxies
SOCKS5 is available on our ISP proxies and ISP subnets: switch the plan's auth mode to SOCKS5 user:pass in the dashboard, then use the same host, port, username and password in a socks5h:// URL. Rotating residential and mobile plans use user:pass over HTTP(S), so use an http:// proxy URL for those. The dashboard steps are in SOCKS5 proxy setup; if you are still choosing a protocol, read SOCKS5 vs HTTP proxies. Dedicated endpoints for the scripts above: SOCKS5 proxies from $0.75/IP per month.
For 100+ IPs, /24 subnets or reseller volume, bulk tiers are on the pricing page.
Frequently Asked Questions
Both use the SOCKS5 protocol. With socks5:// your machine resolves the hostname and sends the proxy an IP address; with socks5h:// the client sends the hostname and the proxy resolves DNS. With socks5h the target lookup no longer goes through your local resolver.
Use socks5h in almost every case. The target lookups then happen on the proxy side instead of on your own resolver, which removes one mismatch between your exit IP and your DNS traffic. Use plain socks5 only if you deliberately want your own resolver's answer.
Put the scheme in the proxy URL: curl -x "socks5h://USERNAME:PASSWORD@PROXY_HOST:PROXY_PORT" https://example.com, or use --socks5-hostname PROXY_HOST:PROXY_PORT -U USERNAME:PASSWORD. Run it with -v and look for "(remotely resolved)" to confirm.
Requests needs PySocks for any socks5:// or socks5h:// proxy. Install it with pip install "requests[socks]" in the same environment that runs your script, then set both the http and https keys in proxies.
According to Chromium's proxy documentation, Chrome always resolves names on the proxy side for SOCKS5, so --proxy-server="socks5://PROXY_HOST:PROXY_PORT" already behaves like socks5h. The same docs say Chrome supports no SOCKS5 authentication methods, so a proxy that needs a username and password won't work there directly.
ISP proxies and ISP subnets: switch the plan's auth mode to SOCKS5 user:pass in the dashboard. SOCKS5 ISP proxies start from $0.75/IP per month. Rotating residential and mobile plans use user:pass over HTTP(S).
- socks5h
- socks5
- dns leak
- curl
- python requests
- node.js
