On this page
What the h in socks5h changes
SOCKS5 is defined in RFC 1928. 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.
| 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 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 sendsATYP 0x03and 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 sendsATYP 0x01or0x04with an address. The SOCKS request carries no name, although the TLS SNI that follows usually still does, as the post on TLS passthrough 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.
# 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.
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:
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=443With 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 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 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 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 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, 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 "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.
# 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 -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, 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 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.
| Client | With socks5:// | With socks5h:// | Basis |
|---|---|---|---|
| curl 8.21.0 | Resolves locally, sent an IPv6 address | Sends the name | libcurl docs, tested |
| Python requests 2.34 (urllib3 and PySocks) | Resolves locally, sent an IPv4 address | Sends the name | urllib3 source, tested |
| Python httpx 0.28.1 | Sends the name | Sends the name | httpx changelog, tested |
| Go net/http 1.26 | Sends the name | Sends the name | Go commit, tested |
| Go golang.org/x/net/proxy | Sends the name | Sends the name | x/net commit |
| Node socks-proxy-agent 10.1 | Resolves with dns.lookup, sent an IPv4 address | Sends the name | source, tested |
| Chrome | Proxy resolves, always | No separate option | Chromium proxy docs |
| Firefox 128 and later | SOCKS v5 setting resolves on the proxy by default | No separate option | Release notes |
- curl decides by scheme.
--socks5-hostnameis the flag form ofsocks5h://, andALL_PROXY=socks5h://...works for the environment too. - Python requests says it directly in its SOCKS docs. "Using the scheme socks5 causes the DNS resolution to happen on the client." urllib3 maps
socks5tordns = Falseandsocks5htordns = True, and its docstring recommendssocks5h://. - PySocks used directly takes an
rdnsargument inset_proxy. Per the PySocks README, "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/httpdocs 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 = trueforsocks5andsocks4, then callsdns.lookupbefore connecting. It also maps a baresocks://URL to thesocks5hbehaviour. - Chrome's docs say that with SOCKSv5 "name resolution is always done proxy side." Firefox controls it with the
network.proxy.socks5_remote_dnspreference, added in bug 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.
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# 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)// 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();
});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 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 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 match the name your client sends, never an IP address. With
socks5://your client may send an IP, and a host rule such asapi.razorpay.comwill not match it. - Private names such as
db.internaldo not resolve on the proxy. Use the service's public hostname, as the troubleshooting guide notes. - Plain SOCKS5 on port 1080 sends your token in cleartext. Port 1443 serves SOCKS5 inside TLS, and the `fm tunnel` CLI always uses it.
Driver setup for Postgres, MySQL, MongoDB, and Redis is in the databases guide. Language guides for Node, Python, and Go show the SOCKS URL in context. If you want the HTTP side of the same story, read how an HTTP CONNECT proxy works. 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
- libcurl: CURLOPT_PROXY
- everything curl: SOCKS proxy
- Requests: Advanced usage, SOCKS
- urllib3: contrib/socks.py
- PySocks README
- httpx changelog
- Go: net/http support socks5h proxy schema
- Go x/net: proxy support socks5h scheme
- socks-proxy-agent source
- Chromium: Proxy support in Chrome
- Firefox 128.0 release notes
- Mozilla bug 1741375: Proxy DNS by default when using SOCKS v5
- libcurl: error codes
- OpenSSH ssh(1) manual
- Amazon RDS API: CreateDBInstance
- RFC 7871: Client Subnet in DNS Queries

