How to Set Up a SOCKS5 Proxy: The Complete Step-by-Step Guide

What you need before you start

Setting up a SOCKS5 proxy takes about ten minutes if you have the four pieces of information every provider gives you:

• Hostname (or gateway) — for example gate.provider.com
• Port — usually a four- or five-digit number like 7777
• Username — often includes routing directives (country, session ID, sticky flags)
• Password — a random string

If your provider only gave you an IP allowlist instead of user:pass, you'll need to add your public IP to their dashboard first. Grab it from curl ifconfig.me and paste it into their whitelist page. From that point on, any request from that IP will authenticate automatically.

This guide walks through every meaningful configuration surface: browser (Firefox, Chrome), operating system (Windows, macOS, Linux), terminal tools (cURL, wget, ssh), programming languages (Python, Node.js, Go), and scraping frameworks (Playwright, Puppeteer, Scrapy). Skip to the section that matches your stack.

The two SOCKS5 URL schemes you need to know

Every SOCKS5 setup boils down to one URL. There are two forms:

socks5://user:pass@host:port    # DNS resolved locally
socks5h://user:pass@host:port   # DNS resolved by the proxy

Use socks5h (note the trailing h) anywhere you care about privacy or geo accuracy. With plain socks5, your local machine looks up the destination hostname before opening the tunnel, which leaks DNS queries to your ISP and can produce inconsistent geo behavior. With socks5h, the DNS lookup happens at the proxy, so the exit node resolves the target as if it were the client.

For scraping specifically, always use socks5h. The performance cost is negligible and the anonymity gain is real.

Setting up SOCKS5 in Firefox

Firefox has native SOCKS5 support with a real DNS-through-proxy option, which makes it the best browser for testing proxy setups.

1. Open Preferences → Network Settings → Settings. 2. Select "Manual proxy configuration." 3. Enter the SOCKS host and port. Choose "SOCKS v5." 4. Enable "Proxy DNS when using SOCKS v5" — this is the equivalent of the socks5h scheme and is critical. 5. Save.

Firefox does not natively support user:pass authentication for SOCKS5 through the UI. When you make your first request, it will prompt you for credentials, which get cached for the session. For scripted or headless setups, use a proxy-authenticating extension like FoxyProxy Standard, which lets you save multiple SOCKS5 endpoints with credentials and switch between them per-URL pattern.

Verify with https://ipleak.net — your visible IP should match your proxy's exit and your DNS server should also be in the proxy's region, not your ISP's.

Setting up SOCKS5 in Chrome and Chromium

Chrome does not have a native SOCKS5 UI. It respects the system proxy on macOS and Windows, and on Linux it reads the --proxy-server command-line flag. To use SOCKS5 authentication, you need one of three approaches:

Approach A: SwitchyOmega extension. Install SwitchyOmega, create a profile for SOCKS5, enter host/port, save. It does not support user:pass on SOCKS5 (a longstanding Chromium limitation) so you'll need to use it alongside your provider's IP allowlist.

Approach B: Local authenticating proxy. Run a small local proxy like gost or microsocks that authenticates upstream and exposes an unauthenticated SOCKS5 on 127.0.0.1. Point Chrome at 127.0.0.1. This is what most professional users do.

gost -L :1080 -F socks5://user:pass@gate.provider.com:7777

Then launch Chrome with:

chromium --proxy-server="socks5://127.0.0.1:1080" --host-resolver-rules="MAP * ~NOTFOUND , EXCLUDE 127.0.0.1"

The --host-resolver-rules flag is what forces DNS through the proxy in Chromium.

Approach C: Puppeteer/Playwright. For automated Chromium, use the automation framework's native proxy support (covered below) which handles auth properly.

Windows system-wide SOCKS5

Windows 10 and 11 have SOCKS support baked into Settings → Network & Internet → Proxy, but it's HTTP-only in practice — the SOCKS route doesn't accept authentication and doesn't force DNS through the proxy. Don't use it.

Instead, install a local SOCKS→SOCKS bridge like Proxifier (paid, excellent) or run gost as a Windows service. Both give you app-level routing rules (send only Chrome and Firefox through the proxy, leave everything else direct) which is what you actually want.

macOS system-wide SOCKS5

macOS supports SOCKS5 at the system level with authentication:

1. System Settings → Network → your active connection → Details → Proxies. 2. Enable "SOCKS Proxy." 3. Enter host, port, username, password. 4. Save.

Every application that respects the system proxy — Safari, Chrome, most Electron apps — will now route through SOCKS5. Apps that use their own network stack (Firefox, most scraping tools) will need to be configured separately.

Linux SOCKS5 via proxychains

The cleanest Linux approach is proxychains-ng. Install it, edit /etc/proxychains.conf:

strict_chain
proxy_dns
[ProxyList]
socks5 gate.provider.com 7777 user pass

Then prefix any command with proxychains4:

proxychains4 curl https://ifconfig.me
proxychains4 firefox

The proxy_dns directive is the socks5h equivalent. Verify with proxychains4 curl https://ipleak.net/json.

SOCKS5 with cURL

cURL has native SOCKS5 support since 7.21.7. The idiomatic form:

curl -x socks5h://user:pass@gate.provider.com:7777 https://httpbin.org/ip

For providers that use per-request routing directives in the username (like user-country-us-session-abc123):

curl -x socks5h://user-country-us-session-abc123:pass@gate.provider.com:7777 https://httpbin.org/ip

To make cURL always use the proxy without -x, export:

export ALL_PROXY=socks5h://user:pass@gate.provider.com:7777

SOCKS5 with wget

wget's SOCKS support is not native — it goes through libproxy or you need a wrapper. The path of least resistance is torify/proxychains:

proxychains4 wget https://example.com/file.zip

If you must have wget-native SOCKS5, compile wget with --with-ssl and the tsocks preload trick, but this is rarely worth the effort.

SOCKS5 over SSH

SSH ships with a built-in SOCKS5 server via the -D flag. If you have an SSH server you trust, this is a free SOCKS5 proxy:

ssh -D 1080 -N -f user@your-server.com

Now socks5://127.0.0.1:1080 routes through your server. Great for personal privacy, useless for scraping (you have one IP).

SOCKS5 in Python

The go-to library is requests with the PySocks dependency:

import requests

proxies = {
    "http":  "socks5h://user:pass@gate.provider.com:7777",
    "https": "socks5h://user:pass@gate.provider.com:7777",
}

r = requests.get("https://httpbin.org/ip", proxies=proxies, timeout=15)
print(r.json())

Install with pip install "requests[socks]" — this pulls PySocks automatically.

For async work, httpx supports SOCKS5 via the httpx-socks package:

import httpx
from httpx_socks import AsyncProxyTransport

transport = AsyncProxyTransport.from_url("socks5://user:pass@gate.provider.com:7777")
async with httpx.AsyncClient(transport=transport) as client:
    r = await client.get("https://httpbin.org/ip")

SOCKS5 in Node.js

The cleanest Node option is socks-proxy-agent:

import { SocksProxyAgent } from 'socks-proxy-agent';

const agent = new SocksProxyAgent(
  'socks5://user:pass@gate.provider.com:7777'
);

const res = await fetch('https://httpbin.org/ip', { agent });
console.log(await res.json());

For axios, pass the same agent as httpsAgent. For undici (Node 18+ native fetch), use ProxyAgent — but note that as of writing, undici's ProxyAgent doesn't support SOCKS5 natively; you still need socks-proxy-agent as a shim.

SOCKS5 in Go

Go's net package has a golang.org/x/net/proxy extension:

import (
    "golang.org/x/net/proxy"
    "net/http"
)

dialer, _ := proxy.SOCKS5("tcp", "gate.provider.com:7777",
    &proxy.Auth{User: "user", Password: "pass"}, proxy.Direct)

transport := &http.Transport{Dial: dialer.Dial}
client := &http.Client{Transport: transport}
resp, _ := client.Get("https://httpbin.org/ip")

Note that Go's stdlib SOCKS5 dialer doesn't send DNS through the proxy. For that, use h12.io/socks which supports socks5h semantics.

SOCKS5 with Playwright

Playwright supports proxies at the browser context level:

const browser = await chromium.launch({
  proxy: {
    server: 'socks5://gate.provider.com:7777',
    username: 'user',
    password: 'pass',
  },
});

Playwright's Chromium routes DNS through the proxy automatically for SOCKS5. Verify with a run against https://ipleak.net/json.

SOCKS5 with Puppeteer

Puppeteer requires launching Chromium with the proxy flag directly, and authentication happens via page.authenticate:

const browser = await puppeteer.launch({
  args: ['--proxy-server=socks5://gate.provider.com:7777'],
});
const page = await browser.newPage();
await page.authenticate({ username: 'user', password: 'pass' });

SOCKS5 with Scrapy

Scrapy needs middleware. The easiest path is scrapy-rotating-proxies or a custom downloader middleware. The minimal working config:

# settings.py
DOWNLOADER_MIDDLEWARES = {
    'scrapy.downloadermiddlewares.httpproxy.HttpProxyMiddleware': 750,
}

# In your spider
def start_requests(self):
    proxy = "socks5h://user:pass@gate.provider.com:7777"
    for url in self.start_urls:
        yield scrapy.Request(url, meta={"proxy": proxy})

Scrapy itself doesn't speak SOCKS5 natively — it treats socks5:// URLs as opaque proxy URLs and relies on Twisted, which supports them via txsocksx. Install pip install txsocksx to make this work reliably.

Verifying your setup

The three checks every setup should pass:

1. IP check: curl -x socks5h://... https://httpbin.org/ip returns an IP that is NOT yours. 2. DNS check: https://ipleak.net/json shows a DNS server in the proxy's region, not your ISP's. 3. WebRTC check: for browsers, visit https://ipleak.net and confirm no WebRTC leaks (WebRTC can reveal your real IP even through a proxy).

If any check fails, don't proceed — you have a leak. Fix the leak before running any real workload.

Common troubleshooting

"Proxy CONNECT aborted": usually wrong credentials or wrong port. Double-check both.

"SOCKS5 requested but not compiled in": your cURL was built without SOCKS support. On macOS use Homebrew's cURL, on Ubuntu apt install curl gives you a SOCKS-enabled build.

"Connection reset by peer": often IP allowlist mismatch (your public IP changed) or your provider rate-limited you.

Success rate suddenly dropped: rotate sessions, switch geo, or open a ticket. Providers occasionally lose ISP partnerships and pool quality drops for a few hours.

"Timeout": your provider's gateway may route through an overloaded region. Most providers offer regional gateways (e.g. gate-us.provider.com) — pick the one closest to your target, not to you.

Set up correctly, a SOCKS5 proxy is invisible: your traffic goes out through the proxy exit, DNS resolves at the exit, and your real IP never touches the destination server. If you can verify all three, you're done.