cURL Reference · 1 min read

curl with a SOCKS5 proxy: the complete reference

The definitive curl-and-proxy reference: SOCKS5 vs SOCKS5h, the -x and --socks5-hostname flags, environment variables, a persistent .curlrc, and authenticated s4m endpoints. Copy-paste ready.

Get started

SOCKS5 vs SOCKS5h, and why it matters

curl supports HTTP and SOCKS proxies. socks5:// resolves target names locally; socks5h:// sends the hostname to the proxy for resolution. The --socks5-hostname option also selects remote DNS. This does not encrypt the SOCKS negotiation or username/password authentication. HTTPS with certificate verification protects application content. Protect the client-to-proxy path with an encrypted tunnel when required; remote DNS is not a substitute for it.

s4m gives you both protocols on one account: SOCKS5 on port 1080 and HTTP on port 3128, both authenticated with USER:PASS against proxy.s4m.online. The generic -x / --proxy flag accepts a full URL including the scheme, so a single flag covers every case. For the basics of routing curl through a proxy, see the curl proxy guide; this page is the deeper reference for SOCKS5, environment variables and persistent config. Background on the protocols lives in what is SOCKS5.

curl · RFC 1929

Every proxy invocation, one place

Use the host and credentials issued to your account. These examples select a proxy explicitly. Review existing configuration before editing it; the config lines below are comments, not commands that overwrite a file.

bash

# Replace the host and dummy USER:PASS with your issued configuration.
PROXY_HOST='HOST_FROM_ACCOUNT'

# SOCKS5 with remote target DNS; this does not encrypt SOCKS authentication.
curl --noproxy "" --proxy "socks5h://$PROXY_HOST:1080" --proxy-user USER:PASS https://api.ipify.org

# Equivalent remote-DNS option with explicit authentication.
curl --noproxy "" --socks5-hostname "$PROXY_HOST:1080" --proxy-user USER:PASS https://api.ipify.org

# SOCKS5 with local target DNS, if that is specifically intended.
curl --noproxy "" --proxy "socks5://$PROXY_HOST:1080" --proxy-user USER:PASS https://api.ipify.org

# Plain HTTP proxy carrying HTTPS with CONNECT; keep TLS verification on.
curl --noproxy "" --proxy "http://$PROXY_HOST:3128" --proxy-user USER:PASS https://api.ipify.org

# Example default-config entries: edit your existing ~/.curlrc, preserving
# other settings. Protect a file containing credentials; do not commit it.
# proxy = "socks5h://HOST_FROM_ACCOUNT:1080"
# proxy-user = "USER:PASS"
# connect-timeout = 10

# Ignore the default config for this call while KEEPING an explicit proxy.
# -q must be the first curl option. Empty --noproxy clears bypass exclusions.
curl -q --noproxy "" --proxy "socks5h://$PROXY_HOST:1080" --proxy-user USER:PASS https://api.ipify.org

Set up a persistent proxy for curl

Choose explicit defaults and verify the actual route, including any bypass rules.

Pick a scheme

Use socks5h:// for proxy-side target DNS, or http:// for an HTTP proxy carrying HTTPS with CONNECT. Check the issued host, port and supported traffic. Neither choice alone encrypts the client-to-proxy connection.

Create ~/.curlrc

Inspect the existing default config before editing it. Preserve other options and protect any stored credentials. curl normally reads this file first; -q as the first option skips it. Keep an explicit proxy when testing without the file.

Set environment variables for other tools

Check each tool separately. In curl, scheme-specific proxy variables take precedence over ALL_PROXY; NO_PROXY can bypass the proxy. Other tools do not necessarily support the same variables or SOCKS schemes.

Verify and add exceptions

Check the exit for the actual request using an IP-echo endpoint. NO_PROXY and --noproxy deliberately allow direct connections for matching hosts; use exceptions only when that bypass is intended.

Auth options, precedence and NTLM

Supply credentials inline in a proxy URL or with -U / --proxy-user. URL-encode reserved characters when embedding credentials in a URL. Keep secrets out of logs and shared files. curl reads its default ~/.curlrc before ordinary command-line options; a later explicit proxy setting can override an earlier one. Proxy configuration takes precedence over environment fallback, and NO_PROXY can still cause a bypass. Use -q as the first option to skip the default file, then specify the intended proxy explicitly.

SOCKS5 username/password negotiation and HTTP Basic proxy authentication are different protocols; the SOCKS exchange is not HTTP Basic. Neither provides encryption by itself. --proxy-ntlm is for HTTP proxies that require NTLM, not for ordinary SOCKS5 username/password access. For 407 Proxy Authentication Required, check the HTTP proxy authentication method and issued credentials; a SOCKS5 failure has a different protocol response. See the 407 guide, wget guide, tools and separate free public list.

FAQ

Questions, answered

What is the difference between socks5 and socks5h in curl?

socks5:// resolves the target name locally; socks5h:// asks the proxy to resolve it. --socks5-hostname also selects proxy-side resolution. This does not encrypt SOCKS authentication; keep HTTPS certificate verification enabled for application traffic.

How do I make curl use a proxy for every command?

Configure the default proxy in your existing curl config, or use supported environment variables. Explicit proxy options, scheme-specific variables and bypass exclusions affect the result. -q skips the default file; it does not itself select or preserve a proxy.

Does s4m need NTLM proxy authentication?

Use the method specified for the issued endpoint. SOCKS5 username/password negotiation is not HTTP Basic; an HTTP proxy can use HTTP Basic. --proxy-ntlm applies only to HTTP proxies that require NTLM, not ordinary SOCKS5 access.

Why do I get 407 Proxy Authentication Required?

An HTTP proxy is requesting authentication. Check the issued username/password and supported authentication method. Encode reserved characters if credentials are embedded in a URL. SOCKS5 authentication failures are reported differently; do not diagnose them as HTTP 407.

Keep reading

One endpoint, every curl trick

Configure s4m SOCKS5 or HTTP access with the credentials from your account.

See proxy pricing See pricing

People found this page by searching for

curl with a SOCKS5 proxy
curl with a SOCKS5 proxy for beginners
curl with a SOCKS5 proxy comparison
curl with a SOCKS5 proxy for scraping
curl with a SOCKS5 proxy tutorial
how to set up proxy for scraping
how to rotate proxies in Python (requests and aiohttp)
how to check proxy authentication
browser fingerprinting
http proxy provider
wireguard
how to avoid IP bans when scraping

Real search phrases this page answers — the linked ones open the page that covers them in depth.