Skip to content
CleanProxies
Get Started

socks5h vs socks5: Remote DNS in curl, Python and Node (With Code)

14 Min Read

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.com

What 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 URLWho resolves DNSWhat the proxy receivesTypical result
socks5://Your machine (local resolver)An IP addressThe lookup for the target goes through your local resolver; the proxy cannot change a wrong or blocked answer
socks5h://The proxyThe hostname, e.g. example.comThe lookup for the target happens on the proxy side, with the proxy's resolver
socks4://Your machineIPv4 onlyNo IPv6, no auth beyond a user ID
socks4a://The proxyThe hostnameThe 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. With socks5h:// 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, .onion addresses through a Tor SOCKS port, or names your local resolver blocks fail with socks5:// and work with socks5h://. 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.py

curl, 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.txt

Output (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.test

curl 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.txt
curl: (6) Could not resolve host: internal.test
hello from internal.test

What 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:8080

With 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

OptionDNSNotes
-x socks5://... or --socks5 host:portLocal-U user:pass for auth with --socks5
-x socks5h://... or --socks5-hostname host:portRemoteSame flags, hostname sent to the proxy
ALL_PROXY=socks5h://... env varRemotePicked 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
echo

If 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.test

Note 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-agent

Save 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.test

getaddrinfo 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

ToolWhere DNS is resolvedCredentials
curlsocks5:// / --socks5: local. socks5h:// / --socks5-hostname: proxyIn the URL or -U
Python Requests (+ PySocks)socks5://: local. socks5h://: proxyIn the URL
Node socks-proxy-agentsocks5://: local. socks5h://: proxyIn 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 httpxInstall pip install "httpx[socks]" and pass proxy="socks5://..." (httpx docs); the docs don't state where DNS is resolvedIn 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

  1. curl verbose: run with -v and look for (remotely resolved) vs (locally resolved), as in the demo above. This is the clearest signal.

  2. Use a hostname your resolver can't answer, like the internal.test mapping above: it only works if the proxy does the lookup.

  3. Watch your own DNS traffic as a hint: on Linux or macOS, sudo tcpdump -n -i any port 53 in a second terminal. A query for the target name while you use socks5h:// means something resolved locally; no query is not proof on its own, because caching, the hosts file or encrypted DNS can also hide it.

  4. Check the exit IP from the same client: request https://api.ipify.org through the proxy in the same script (the default TARGET_URL above 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

ErrorWhereLikely causeFix
InvalidSchema: Missing dependencies for SOCKS support.Python RequestsPySocks not installed in this environmentpip install "requests[socks]" in the same environment that runs the script
SOCKSHTTPConnectionPool ... Name or service not known (or SOCKSHTTPSConnectionPool for HTTPS)Python Requestssocks5:// resolved locally and the name failedSwitch to socks5h://
curl: (6) Could not resolve hostcurlLocal DNS lookup failed with --socks5 / socks5://Use socks5h:// or --socks5-hostname
getaddrinfo ENOTFOUNDNode.jsLocal lookup with a socks5:// agentUse a socks5h:// agent URL
Failed to receive SOCKS5 connect request ackcurlThe 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 RequiredAnyThis is an HTTP-proxy response, so you are talking to an HTTP proxy port or using an http:// proxy URL, with wrong or missing credentialsFix 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).

Team CleanProxies
Proxy Infrastructure Team
Tags
  • socks5h
  • socks5
  • dns leak
  • curl
  • python requests
  • node.js

Related Articles