---
title: "socks5 vs socks5h: Who Resolves the Hostname"
description: "socks5:// and socks5h:// differ in who resolves the hostname. See the bytes on the wire, how DNS leaks and split-horizon bite, and which clients do what."
canonical: https://fixedmark.com/blog/socks5-vs-socks5h-dns-resolution
updated: 2026-11-10
source: Fixedmark (https://fixedmark.com), BitMask LLP
---

Networking · 10 min read

# socks5 vs socks5h: Who Resolves the Hostname

With \`socks5://\`, many clients, including curl, Python requests, and Node's socks-proxy-agent, look up the hostname themselves and send the proxy an IP address. With \`socks5h://\`, the client sends the hostname and the proxy resolves it. Use \`socks5h://\` with a remote proxy, so the lookup happens where the connection leaves and your local resolver never sees the name.

## What the h in socks5h changes

SOCKS5 is defined in [RFC 1928](https://www.rfc-editor.org/rfc/rfc1928). After a short greeting and optional authentication, the client sends one request that names the destination. The request has six fields, `VER CMD RSV ATYP DST.ADDR DST.PORT`. The `ATYP` byte says what kind of address follows.

_SOCKS5 address types in RFC 1928_

| ATYP   | Meaning      | DST.ADDR holds                                        |
| ------ | ------------ | ----------------------------------------------------- |
| `0x01` | IPv4 address | 4 bytes                                               |
| `0x03` | Domain name  | 1 length byte, then the name, with no terminating NUL |
| `0x04` | IPv6 address | 16 bytes                                              |

So the protocol has always let a client send a name. The RFC does not say who should resolve it. That choice belongs to the client, and the `h` suffix is how you tell the client which one you want.

The `socks5h://` scheme is not part of the RFC. It comes from curl. The [libcurl CURLOPT_PROXY page](https://curl.se/libcurl/c/CURLOPT_PROXY.html) lists `socks5://` as a plain SOCKS5 proxy and `socks5h://` as SOCKS5 where the "Proxy resolves URL hostname." The same split exists for version 4. Plain SOCKS4 can only carry an IPv4 address, so curl resolves the name. SOCKS4a adds a way to send the name, and the proxy resolves it. Python, Node, and Go libraries copied the curl spelling, but not always the curl behaviour.

- With `socks5h://`, the client sends `ATYP 0x03` and the hostname. The proxy runs the DNS lookup with its own resolver and dials the result.
- With `socks5://`, a client that follows curl resolves the name locally and sends `ATYP 0x01` or `0x04` with an address. The SOCKS request carries no name, although the TLS SNI that follows usually still does, as the post on [TLS passthrough](https://fixedmark.com/blog/tls-passthrough-zero-knowledge-proxy) explains.

One thing does not change. The proxy opens the TCP connection in both cases, so the destination sees the proxy's IP either way. If a partner allowlists your proxy's address, both schemes pass that check. The differences are about which name gets looked up, by whom, and which address gets dialed.

## Watch the request on the wire

The quickest way to see the difference is a proxy that prints what it receives. This toy server speaks just enough SOCKS5 to log the address type, then relays the connection. It resolves names over IPv4 only, like many egress proxies whose public addresses are IPv4. It skips authentication, so run it on localhost only.

**socks_log.py**

```python
# A toy SOCKS5 proxy that prints what each client asks for. Local testing only.
import asyncio
import ipaddress
import socket

ATYP = {1: "IPv4", 3: "DOMAINNAME", 4: "IPv6"}

async def pipe(reader, writer):
    try:
        while data := await reader.read(65536):
            writer.write(data)
            await writer.drain()
    finally:
        writer.close()

async def handle(reader, writer):
    _ver, nmethods = await reader.readexactly(2)
    await reader.readexactly(nmethods)
    writer.write(b"\x05\x00")  # no authentication
    _ver, _cmd, _rsv, atyp = await reader.readexactly(4)
    if atyp == 1:
        host = str(ipaddress.IPv4Address(await reader.readexactly(4)))
    elif atyp == 4:
        host = str(ipaddress.IPv6Address(await reader.readexactly(16)))
    else:
        (length,) = await reader.readexactly(1)
        host = (await reader.readexactly(length)).decode()
    port = int.from_bytes(await reader.readexactly(2), "big")
    print(f"ATYP={atyp:#04x} ({ATYP[atyp]})  DST.ADDR={host}  DST.PORT={port}", flush=True)

    try:
        # A DOMAINNAME is resolved here, on the proxy, over IPv4 only.
        up_r, up_w = await asyncio.open_connection(host, port, family=socket.AF_INET)
    except OSError:
        writer.write(b"\x05\x04\x00\x01" + bytes(6))  # REP 0x04, host unreachable
        writer.close()
        return
    writer.write(b"\x05\x00\x00\x01" + bytes(6))  # REP 0x00, succeeded
    await asyncio.gather(pipe(reader, up_w), pipe(up_r, writer))

async def main():
    server = await asyncio.start_server(handle, "127.0.0.1", 1080)
    async with server:
        await server.serve_forever()

asyncio.run(main())
```

Start it with `python3 socks_log.py`, then send the same request three ways from another terminal.

**Terminal**

```bash
curl -s -o /dev/null -w "%{http_code}\n" --proxy socks5://127.0.0.1:1080 https://example.com/
curl -s -o /dev/null -w "%{http_code}\n" --proxy socks5h://127.0.0.1:1080 https://example.com/
curl -s -o /dev/null -w "%{http_code}\n" --socks5-hostname 127.0.0.1:1080 https://example.com/
```

On a Linux machine with IPv6 and curl 8.21.0, the first command printed `000` and the other two printed `200`. The proxy logged this:

**Proxy output**

```
ATYP=0x04 (IPv6)  DST.ADDR=2606:4700:10::ac42:93f3  DST.PORT=443
ATYP=0x03 (DOMAINNAME)  DST.ADDR=example.com  DST.PORT=443
ATYP=0x03 (DOMAINNAME)  DST.ADDR=example.com  DST.PORT=443
```

With `socks5://`, curl looked up `example.com`, preferred the IPv6 answer, and asked the proxy to dial an IPv6 address. The proxy could not, and curl reported `cannot complete SOCKS5 connection to example.com. (4)`. The `(4)` is the RFC 1928 reply code for host unreachable. With `socks5h://` or `--socks5-hostname`, the proxy got the name, resolved an IPv4 address itself, and the request worked.

curl's verbose output also tells you which path it took. With `socks5://`, `curl -v` prints `Host example.com:443 was resolved.` followed by the IPv6 and IPv4 answers before the SOCKS handshake. With `socks5h://` it prints no lookup, only `Opened SOCKS connection from 127.0.0.1 port ... to example.com port 443`. The [everything curl SOCKS chapter](https://everything.curl.dev/usingcurl/proxies/socks.html) has the full table of SOCKS variants and who resolves for each.

## Why local resolution causes trouble

Resolving locally is not wrong in itself. It goes wrong when the client and the proxy sit in different networks, which is the whole point of a remote proxy.

### Your local resolver sees every name

With `socks5://`, every hostname you visit goes to the resolver your machine or platform uses, in clear text unless it runs DNS over TLS or HTTPS. That is the classic DNS leak. The traffic is proxied, but the list of destinations is not. Firefox treated this as a bug worth fixing. Its [128.0 release notes](https://www.firefox.com/en-US/firefox/128.0/releasenotes/) say it "now proxies DNS by default when using SOCKS v5, avoiding leaking DNS queries to the network."

One lookup still happens locally with either scheme. Your client resolves the proxy's own hostname, because it has to reach the proxy first. Only the destination name moves.

### Geo-DNS answers for the wrong place

CDNs and large APIs answer DNS by location. [RFC 7871](https://www.rfc-editor.org/rfc/rfc7871) puts it plainly. "Many Authoritative Nameservers today return different responses based on the perceived topological location of the user." If your app runs in the US and your proxy runs in Mumbai, a local lookup can return a US edge address. The proxy then carries your traffic from Mumbai back to that US edge, which adds a long round trip to every connection. With `socks5h://` the lookup comes from the proxy's network and gets an answer near the proxy.

### IPv6 answers an IPv4 proxy cannot dial

The curl run above shows this one. Your laptop or platform may have IPv6, and the client may pick the AAAA record. Many egress proxies, and many partner allowlists, are IPv4 only. The proxy receives an IPv6 address it cannot use and fails the request. `curl -4` works around it in curl. `socks5h://` fixes it properly, because the proxy chooses an address family it can actually dial. The post on [IPv6 egress and IPv4-only allowlists](https://fixedmark.com/blog/ipv6-egress-and-ipv4-only-allowlists) covers the wider problem.

### Host-based proxy rules see only an IP

Some proxies let you restrict a credential to certain destinations by name, such as `api.razorpay.com`. Those rules need a name to match. With `socks5://` the proxy receives an address, so a host rule cannot match it, and you would need an IP range rule instead. That defeats the point of naming the host.

### Some lookups never go through SOCKS

A SOCKS5 CONNECT carries one host and one port. It has no way to ask the proxy for SRV or TXT records. Protocols that need them still look them up locally, whatever the scheme. A `mongodb+srv://` connection string is the common case. The driver resolves the SRV and TXT records itself, then opens each member connection through the proxy. That is usually fine, because an IP access list checks the TCP connections, not the DNS queries.

## Split-horizon and private DNS

Split-horizon DNS means one name returns different answers depending on who asks. Corporate networks do it for internal names. Clouds do it for managed services. Who resolves the name decides which view you get.

Amazon RDS is a clear example. Per the [CreateDBInstance reference](https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_CreateDBInstance.html), when an instance is publicly accessible and you connect from outside its VPC, its DNS endpoint "resolves to the public IP address." From inside the same VPC, "the endpoint resolves to the private IP address." An instance that is not publicly accessible has a name that resolves only to a private address.

### When the proxy is inside the private network

The common case is an SSH bastion. `ssh -D` opens a local SOCKS port, and per the [OpenSSH manual](https://man.openbsd.org/ssh) "ssh will act as a SOCKS server," connecting out from the remote machine. Here you want the bastion to resolve names, because it sits inside the VPC and sees the private answers.

**Terminal**

```bash
# Local SOCKS port 1080, connections leave from the bastion
ssh -N -D 1080 ec2-user@bastion.example.com

# The bastion resolves the internal name and reaches it
curl --proxy socks5h://127.0.0.1:1080 http://grafana.internal.example.com/

# Your laptop resolves it instead, and gets no answer or the wrong one
curl --proxy socks5://127.0.0.1:1080 http://grafana.internal.example.com/
```

### When the proxy is on the public internet

A static IP egress proxy is the reverse. It resolves names with public DNS, so it cannot see your VPC's private zone or your office's internal names. A private name fails on the proxy with `socks5h://`, and with `socks5://` it may resolve on your side to a private address the proxy cannot reach. In a quick test against the toy proxy, the two schemes failed in different places.

**curl 8.21.0 output**

```
$ curl -sS --proxy socks5://127.0.0.1:1080 https://db.internal/
curl: (6) Could not resolve host: db.internal

$ curl -sS --proxy socks5h://127.0.0.1:1080 https://db.internal/
curl: (97) cannot complete SOCKS5 connection to db.internal. (4)
```

Exit code 6 means your machine could not resolve the name. Per the [libcurl error list](https://curl.se/libcurl/c/libcurl-errors.html), 97 is a proxy handshake error, and the number in brackets is the SOCKS reply code from the proxy. Knowing which side failed tells you which resolver to look at. For a database behind an allowlist, use the public hostname the provider gives you, and let the proxy resolve it. The post on [database connections through SOCKS5](https://fixedmark.com/blog/database-connections-through-socks5-pooling) goes further into pools and timeouts.

## Which clients do what

Not every library follows curl. Some send the name for both schemes, which is safe. Some resolve locally for `socks5://`, which leaks. The rows marked tested were run against the toy proxy above in November 2026. The others come from each project's docs or source.

_What each client sends to a SOCKS5 proxy_

| Client                                     | With socks5://                                    | With socks5h://    | Basis                                                                                                            |
| ------------------------------------------ | ------------------------------------------------- | ------------------ | ---------------------------------------------------------------------------------------------------------------- |
| curl 8.21.0                                | Resolves locally, sent an IPv6 address            | Sends the name     | [libcurl docs](https://curl.se/libcurl/c/CURLOPT_PROXY.html) , tested                                            |
| Python requests 2.34 (urllib3 and PySocks) | Resolves locally, sent an IPv4 address            | Sends the name     | [urllib3 source](https://raw.githubusercontent.com/urllib3/urllib3/main/src/urllib3/contrib/socks.py) , tested   |
| Python httpx 0.28.1                        | Sends the name                                    | Sends the name     | [httpx changelog](https://github.com/encode/httpx/blob/master/CHANGELOG.md) , tested                             |
| Go net/http 1.26                           | Sends the name                                    | Sends the name     | [Go commit](https://go.googlesource.com/go/+/c8e4f8c7756d67e27d2cfe4383cb90cf9f97d5a3%5E%21) , tested            |
| Go golang.org/x/net/proxy                  | Sends the name                                    | Sends the name     | [x/net commit](https://go.googlesource.com/net/+/395948e2f546cb82afa9e1f6d1a6e87849b9af1d)                       |
| Node socks-proxy-agent 10.1                | Resolves with `dns.lookup`, sent an IPv4 address  | Sends the name     | [source](https://github.com/TooTallNate/proxy-agents/blob/main/packages/socks-proxy-agent/src/index.ts) , tested |
| Chrome                                     | Proxy resolves, always                            | No separate option | [Chromium proxy docs](https://chromium.googlesource.com/chromium/src/+/HEAD/net/docs/proxy.md)                   |
| Firefox 128 and later                      | SOCKS v5 setting resolves on the proxy by default | No separate option | [Release notes](https://www.firefox.com/en-US/firefox/128.0/releasenotes/)                                       |

- curl decides by scheme. `--socks5-hostname` is the flag form of `socks5h://`, and `ALL_PROXY=socks5h://...` works for the environment too.
- Python requests says it directly in its [SOCKS docs](https://requests.readthedocs.io/en/latest/user/advanced/#socks). "Using the scheme socks5 causes the DNS resolution to happen on the client." urllib3 maps `socks5` to `rdns = False` and `socks5h` to `rdns = True`, and its docstring recommends `socks5h://`.
- PySocks used directly takes an `rdns` argument in `set_proxy`. Per the [PySocks README](https://github.com/Anorov/PySocks), "The default is True," so a bare PySocks socket resolves on the proxy unless you turn it off.
- httpx accepts both schemes since 0.28.0, which added "Treat socks5h as a valid proxy scheme." In 0.28.1 both send the name.
- Go's `net/http` docs say "socks5" is treated the same as "socks5h". The x/net commit that added the scheme says the "Go SOCKS5 client always uses the server to resolve host names."
- socks-proxy-agent sets `lookup = true` for `socks5` and `socks4`, then calls `dns.lookup` before connecting. It also maps a bare `socks://` URL to the `socks5h` behaviour.
- Chrome's docs say that with SOCKSv5 "name resolution is always done proxy side." Firefox controls it with the `network.proxy.socks5_remote_dns` preference, added in [bug 1741375](https://bugzilla.mozilla.org/show_bug.cgi?id=1741375), shown as "Proxy DNS when using SOCKS v5" in the connection settings.

Two habits avoid most surprises. Always write `socks5h://` when you mean remote resolution, even in a client that ignores the difference, so the URL still works if someone moves it to curl or requests. And spell out the version, because a bare `socks://` means different things in different tools.

## Setting socks5h in your client

Each snippet reads the proxy URL from the environment, so the scheme lives in one place. Swap the example URL for your own.

**curl**

```bash
export SOCKS_URL="socks5h://user:pass@proxy.example.com:1080"

# Per command
curl --proxy "$SOCKS_URL" https://api.example.com/health

# For every curl call in this shell, and for tools built on libcurl
export ALL_PROXY="$SOCKS_URL"
curl https://api.example.com/health
```

**Python**

```python
# pip install "requests[socks]"
import os
import requests

socks = os.environ["SOCKS_URL"]  # socks5h://user:pass@proxy.example.com:1080
res = requests.get(
    "https://api.example.com/health",
    proxies={"http": socks, "https": socks},
    timeout=15,
)
print(res.status_code)
```

**Node.js**

```javascript
// npm install socks-proxy-agent
import https from "node:https";
import { SocksProxyAgent } from "socks-proxy-agent";

// socks5h:// skips the local dns.lookup and sends the name to the proxy.
const agent = new SocksProxyAgent(process.env.SOCKS_URL);

https.get("https://api.example.com/health", { agent }, (res) => {
  console.log(res.statusCode);
  res.resume();
});
```

**Go**

```go
package main

import (
	"fmt"
	"log"
	"net/http"
	"net/url"
	"os"
)

func main() {
	// Go sends the host name for socks5 and socks5h alike.
	u, err := url.Parse(os.Getenv("SOCKS_URL"))
	if err != nil {
		log.Fatal(err)
	}
	client := &http.Client{Transport: &http.Transport{Proxy: http.ProxyURL(u)}}
	res, err := client.Get("https://api.example.com/health")
	if err != nil {
		log.Fatal(err)
	}
	defer res.Body.Close()
	fmt.Println(res.StatusCode)
}
```

To confirm what your client does, point it at the toy proxy and read the `ATYP` line. Without a toy proxy, watch DNS on the client while you make a request, for example with `sudo tcpdump -n -i any port 53`. If you see a query for the destination name, your client resolved it locally. That check misses DNS over HTTPS and local caches, so the toy proxy is the more reliable test.

Environment variables come with their own parsing rules, and a SOCKS URL in `ALL_PROXY` can catch more traffic than you meant. The post on [NO_PROXY and per-client agents](https://fixedmark.com/blog/selective-proxying-no-proxy-and-per-client-agents) covers that.

## Doing this with Fixedmark

Fixedmark, in early access, gives an app a pair of static IPv4 addresses and a SOCKS5 endpoint for databases, SSH, SFTP, and other TCP traffic. The SOCKS URL the dashboard shows already uses the `h` scheme, for example `socks5h://APP_ID:TOKEN@mum.egress.fixedmark.com:1080`. Keep it that way. The [concepts page](https://fixedmark.com/docs/concepts#socks5) explains why.

- The proxy resolves the name in its region, so geo-DNS answers match the IPs your partner allowlisted.
- The proxy connects over IPv4. A client that resolves locally and sends an IPv6 address cannot leave from your pair, while `socks5h://` lets the proxy pick an IPv4 address.
- [Allowlist host rules](https://fixedmark.com/docs/allowlists) match the name your client sends, never an IP address. With `socks5://` your client may send an IP, and a host rule such as `api.razorpay.com` will not match it.
- Private names such as `db.internal` do not resolve on the proxy. Use the service's public hostname, as the [troubleshooting guide](https://fixedmark.com/docs/troubleshooting#dns) notes.
- Plain SOCKS5 on port 1080 sends your token in cleartext. Port 1443 serves SOCKS5 inside TLS, and the [\`fm tunnel\` CLI](https://fixedmark.com/docs/cli) always uses it.

Driver setup for Postgres, MySQL, MongoDB, and Redis is in the [databases guide](https://fixedmark.com/docs/databases). Language guides for [Node](https://fixedmark.com/docs/node#socks), [Python](https://fixedmark.com/docs/python#socks), and [Go](https://fixedmark.com/docs/go#socks) show the SOCKS URL in context. If you want the HTTP side of the same story, read [how an HTTP CONNECT proxy works](https://fixedmark.com/blog/http-connect-proxy-explained). CONNECT always sends the hostname, so it has no socks5h problem.

## Sources

Checked November 2026. Confirm current details on the vendor's site before you decide. Prices and limits change.

- [RFC 1928: SOCKS Protocol Version 5](https://www.rfc-editor.org/rfc/rfc1928)
- [libcurl: CURLOPT_PROXY](https://curl.se/libcurl/c/CURLOPT_PROXY.html)
- [everything curl: SOCKS proxy](https://everything.curl.dev/usingcurl/proxies/socks.html)
- [Requests: Advanced usage, SOCKS](https://requests.readthedocs.io/en/latest/user/advanced/)
- [urllib3: contrib/socks.py](https://raw.githubusercontent.com/urllib3/urllib3/main/src/urllib3/contrib/socks.py)
- [PySocks README](https://github.com/Anorov/PySocks)
- [httpx changelog](https://github.com/encode/httpx/blob/master/CHANGELOG.md)
- [Go: net/http support socks5h proxy schema](https://go.googlesource.com/go/+/c8e4f8c7756d67e27d2cfe4383cb90cf9f97d5a3%5E%21)
- [Go x/net: proxy support socks5h scheme](https://go.googlesource.com/net/+/395948e2f546cb82afa9e1f6d1a6e87849b9af1d)
- [socks-proxy-agent source](https://github.com/TooTallNate/proxy-agents/blob/main/packages/socks-proxy-agent/src/index.ts)
- [Chromium: Proxy support in Chrome](https://chromium.googlesource.com/chromium/src/+/HEAD/net/docs/proxy.md)
- [Firefox 128.0 release notes](https://www.firefox.com/en-US/firefox/128.0/releasenotes/)
- [Mozilla bug 1741375: Proxy DNS by default when using SOCKS v5](https://bugzilla.mozilla.org/show_bug.cgi?id=1741375)
- [libcurl: error codes](https://curl.se/libcurl/c/libcurl-errors.html)
- [OpenSSH ssh(1) manual](https://man.openbsd.org/ssh)
- [Amazon RDS API: CreateDBInstance](https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_CreateDBInstance.html)
- [RFC 7871: Client Subnet in DNS Queries](https://www.rfc-editor.org/rfc/rfc7871)

Keep reading

## Related guides

- [Use case Postgres and MySQL Allowlist two IPs on RDS, Cloud SQL, or a self-hosted database and connect through SOCKS5 or a local tunnel.](https://fixedmark.com/use-cases/postgres-and-mysql)
- [Use case MongoDB Atlas Replace 0.0.0.0/0 in your Atlas IP access list with two dedicated IPs, using the Node driver's SOCKS5 support.](https://fixedmark.com/use-cases/mongodb-atlas)
- [Use case SFTP allowlisting Reach bank, payroll, and EDI SFTP servers that only accept allowlisted IPs, through SOCKS5 or a local tunnel.](https://fixedmark.com/use-cases/sftp-allowlisting)
- [Guide Fixedmark docs Proxy URLs, SOCKS5, allowlists, and language guides.](https://fixedmark.com/docs)

## Frequently asked questions

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

Both use the SOCKS5 protocol. With socks5h, the client sends the hostname and the proxy resolves it. With socks5, clients that follow curl resolve the hostname locally and send the proxy an IP address. Some clients, such as Go and httpx, send the hostname for both.

### Does socks5h change the IP address the destination sees?

No. The proxy opens the TCP connection with either scheme, so the destination sees the proxy's IP. The scheme only changes who runs the DNS lookup and which address gets dialed.

### Is socks5h part of RFC 1928?

No. RFC 1928 defines a domain name address type that lets a client send a name, but the socks5h:// URL scheme is a convention from curl that other libraries adopted.

### Why does my request fail with socks5 but work with socks5h?

Usually your client resolved the name to an address the proxy cannot use, such as an IPv6 address on an IPv4-only proxy, or a private address from split-horizon DNS. With socks5h the proxy resolves the name in its own network.

### Does socks5h stop every DNS leak?

It moves the destination lookup to the proxy. Your client still resolves the proxy's own hostname, and protocols that need SRV or TXT records, such as mongodb+srv connection strings, still look those up locally.
