socks5h: SOCKS5 with proxy-side DNS resolution
Definition
socks5h sends the hostname to a SOCKS5 proxy for DNS resolution. See the wire difference from socks5 with a real curl capture.
socks5h tells curl to use SOCKS5 while sending the destination hostname to the proxy for DNS resolution. The trailing h means hostname. With plain socks5, curl resolves the name locally and sends an address. The difference affects DNS visibility, regional answers and whether a proxy can apply hostname policy.
Choose one resolver policy for each request and record it in diagnostics when troubleshooting.
Protocol and scheme
RFC 1928 defines the SOCKS Protocol Version 5 handshake. It allows the CONNECT request to carry an IPv4 address, an IPv6 address or a domain name. The RFC does not name the curl URL scheme socks5h. That is curl’s documented spelling for the SOCKS5 domain-name form, also available as --socks5-hostname.
Resolution location is separate from encryption. With https:// the proxy opens a TCP tunnel and the TLS session is between curl and the destination. The proxy still sees the hostname in the SOCKS request and can see timing and byte counts. It does not automatically become an anonymity service.
A wire capture on localhost
We ran curl 8.7.1 against a dependency-free local SOCKS5 listener. The listener returned a deliberate failure after recording the CONNECT request. Python 3.15.0 printed the request tuple:
$ curl -sS --max-time 3 -x socks5h://127.0.0.1:57015 http://example.invalid/
curl: (97) Can't complete SOCKS5 connection to example.invalid. (4)
exit=97
captured_socks5h_request=(5, 1, 3, 'example.invalid', 80)
$ curl -sS --max-time 3 -x socks5://127.0.0.1:57017 http://localhost/
curl: (97) Can't complete SOCKS5 connection to localhost. (4)
exit=97
captured_socks5_request=(5, 1, 4, '::1', 80)
The third tuple field is the address type. Value 3 is a domain name, so the proxy received example.invalid. Value 4 is IPv6, so curl resolved localhost first and sent ::1. The failure is expected because the test server never opened a tunnel. It does not indicate a DNS failure.
| curl form | Resolver | SOCKS CONNECT contains | Useful when |
|---|---|---|---|
socks5:// |
Local curl resolver | IPv4 or IPv6 address | You intentionally need local DNS or have an IP already |
socks5h:// |
Proxy-side resolver | Hostname | The proxy’s network should choose the DNS answer |
--socks5-hostname |
Proxy-side resolver | Hostname | You prefer a long option in scripts |
HTTP -x |
Depends on the HTTP proxy | HTTP request or CONNECT target | The provider exposes an HTTP proxy endpoint |
Choosing it in a client
# Hostname goes to the SOCKS server
curl -x socks5h://user:pass@gateway.example:1080 https://example.com/
# Equivalent long option
curl --socks5-hostname gateway.example:1080 https://example.com/
Keep credentials out of shell history and process listings when your client provides a separate option. For curl, --proxy-user is the separate form. The curl proxy guide covers authentication and response checks, and proxy environment variables explains why one library may read ALL_PROXY while another does not.
SOCKS5 can carry more than HTTP, unlike a protocol-aware HTTP proxy. The existing SOCKS5 reference covers authentication and UDP, while HTTP CONNECT describes the equivalent tunnel operation for an HTTP proxy. If a destination behaves differently by region, compare the DNS answer and the exit address before changing headers. The sticky-session guide helps keep that comparison on one exit.
Use socks5h when the proxy should apply its own resolver policy, such as split-horizon DNS, regional routing, or access to a name resolvable only from the proxy network. Use socks5 when local resolution is intentional and sending an address gives the proxy no hostname to resolve. If the destination is already an IP literal, both forms remove the hostname lookup question, although the address type can still be IPv4 or IPv6.
To diagnose a mismatch, record the local DNS answer and compare it with the destination address observed at the proxy. Check whether the application rewrites the proxy URL, whether an environment variable wins over a command-line option, and whether IPv6 is enabled. A successful SOCKS handshake followed by a connection error is different from a proxy handshake error such as curl’s exit 97. Keep these stages separate in logs.