---
title: "socks5h: SOCKS5 with proxy-side DNS resolution"
url: https://proxy.wiki/glossary/socks5h/
type: Glossary Term
author: "proxy.wiki editorial"
published: 2026-10-21
updated: 2026-10-21
site: proxy.wiki
topics: ["Proxy fundamentals"]
license: CC BY 4.0; quote freely with attribution to https://proxy.wiki/
---

# socks5h: SOCKS5 with proxy-side DNS resolution

> socks5h sends the hostname to a SOCKS5 proxy for DNS resolution. See the wire difference from socks5 with a real curl capture.

## Key takeaways

- socks5h sends a hostname to the SOCKS5 proxy for DNS.
- Plain socks5 resolves locally and sends an address.
- The h changes DNS location, not encryption or proxy trust.

**`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](https://www.rfc-editor.org/rfc/rfc1928.html) 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](/guides/how-to-use-a-proxy-with-curl/) covers authentication and response checks, and [proxy environment variables](/guides/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](/glossary/socks5/) covers authentication and UDP, while [HTTP CONNECT](/glossary/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](/guides/rotating-vs-sticky-sessions/) 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.

## Frequently asked questions

### Does socks5h hide DNS from my network?

It moves the lookup to the proxy, so curl does not ask your local resolver. Your network still sees the proxy connection and the proxy sees the hostname.

### Is socks5h more secure than socks5?

It changes where DNS resolution happens. It does not add encryption or authenticate the proxy. Use HTTPS and verify the proxy separately.

### Why did curl return error 97?

Curl could not complete the SOCKS5 connection. Check the proxy address, port, credentials and whether the proxy can resolve and reach the target.

## Sources

1. [RFC 1928: SOCKS Protocol Version 5](https://www.rfc-editor.org/rfc/rfc1928.html)
2. [RFC 1929: Username/Password Authentication for SOCKS V5](https://www.rfc-editor.org/rfc/rfc1929.html)
3. [everything curl: SOCKS proxy](https://everything.curl.dev/usingcurl/proxies/socks.html)
4. [curl man page: --socks5-hostname](https://curl.se/docs/manpage.html#--socks5-hostname)
5. [libcurl error codes: CURLE_PROXY (97) means proxy handshake error](https://curl.se/libcurl/c/libcurl-errors.html)
