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

Published 2026-11-12 · By Team CleanProxies · [Read on the web](https://www.cleanproxies.com/blogs/socks5h)

> socks5h means the proxy resolves DNS, socks5 means your machine does. Side-by-side output from curl, Python Requests and Node, a tool table, error fixes and how to prove where DNS is resolved.

**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](https://www.cleanproxies.com/socks5-proxies) start from $0.75/IP per month, dedicated and on US carrier ASNs.

Quick reference:

```bash
# 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 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. With `socks5h://` the client skips that lookup for proxied requests. Other apps on the machine still use your normal DNS. See [DNS leak](https://www.cleanproxies.com/glossary/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):

```python
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:

```bash
# 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):

```bash
curl -sSv --noproxy "" -x "socks5://USERNAME:PASSWORD@127.0.0.1:1080" http://localhost:8080/index.txt
curl -sSv --noproxy "" -x "socks5h://USERNAME:PASSWORD@127.0.0.1:1080" http://localhost:8080/index.txt
```

Output (excerpt, filtered to the SOCKS lines and the body):

```text
* 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:**

```bash
curl -sS --noproxy "" -x "socks5://USERNAME:PASSWORD@127.0.0.1:1080" http://internal.test:8080/index.txt
curl -sS --noproxy "" -x "socks5h://USERNAME:PASSWORD@127.0.0.1:1080" http://internal.test:8080/index.txt
```

```text
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):

```text
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

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

```bash
#!/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](https://www.cleanproxies.com/integrations/curl) page.

## Python Requests

Requests speaks SOCKS through PySocks. Install the extra first:

```bash
pip install "requests[socks]"
```

On [PyPI](https://pypi.org/project/requests/) 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:

```text
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:

```python
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:

```text
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](https://www.cleanproxies.com/integrations/python-requests) 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.

```bash
npm install socks-proxy-agent
```

Save as `dns-check.mjs`:

```javascript
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):

```text
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

| 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](https://chromium.googlesource.com/chromium/src/+/HEAD/net/docs/proxy.md) 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](https://www.python-httpx.org/advanced/proxies/)); 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

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](https://www.cleanproxies.com/tools/proxy-checker); [what is my IP](https://www.cleanproxies.com/tools/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](https://www.cleanproxies.com/blogs/socks5-proxy-setup)) |

## Using socks5h with CleanProxies

SOCKS5 is available on our [ISP proxies](https://www.cleanproxies.com/products/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](https://www.cleanproxies.com/blogs/socks5-proxy-setup); if you are still choosing a protocol, read [SOCKS5 vs HTTP proxies](https://www.cleanproxies.com/blogs/socks5-vs-http-proxies). Dedicated endpoints for the scripts above: [SOCKS5 proxies](https://www.cleanproxies.com/socks5-proxies) from $0.75/IP per month.

For 100+ IPs, /24 subnets or reseller volume, bulk tiers are on the [pricing](https://www.cleanproxies.com/pricing) page.

## FAQs

### What is the difference between socks5 and socks5h?

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.

### Should I use socks5h or socks5 for web scraping?

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.

### How do I use socks5h in curl?

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.

### Why does Python Requests say Missing dependencies for SOCKS support?

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.

### Does Chrome support socks5h?

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.

### Which CleanProxies plans support SOCKS5?

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