How-to
How to use a SOCKS5 proxy on macOS — and why the system setting often isn't enough
macOS 13+ · Apple Silicon and Intel · Updated 2026-08-30
The built-in way, in full
macOS has had a SOCKS proxy setting for a long time, and for simple cases it is all you need:
- Open System Settings, go to Network, and select the network service you are actually using.
- Click Details, then the Proxies tab.
- Switch on SOCKS Proxy and enter the host and port, for example 127.0.0.1 and 7890.
- Add anything that must stay local to the bypass list — localhost, 127.0.0.1, your LAN ranges.
- Click OK, then Apply. There is no restart and no per-app step.
The same thing from the command line, which is handy in a script — replace Wi-Fi with your service name:
networksetup -listallnetworkservices networksetup -setsocksfirewallproxy Wi-Fi 127.0.0.1 7890 networksetup -setsocksfirewallproxystate Wi-Fi on # check what is set networksetup -getsocksfirewallproxy Wi-Fi
What that setting actually covers
This is the part that surprises people. The system proxy is not enforced by the operating system — it is published by it. Each application decides whether to read the value and honour it. In practice that splits the software on your Mac into three groups:
| Software | Reads the system SOCKS setting? |
|---|---|
| Safari, Mail, most native Apple apps | Yes |
| Chrome and Edge (default settings) | Yes |
| Firefox | Only if set to use system settings; it has its own by default |
| Electron apps (Slack, Discord, many others) | Usually, but several ship with it disabled |
| Terminal tools: curl, git, npm, pip | No — they read environment variables instead |
| Go, Rust and Java binaries | Varies per program; often not at all |
| Games and voice chat | Almost never |
| Anything using UDP or QUIC | Not covered at all — the setting is TCP only |
The three ways this goes wrong
1. It routes too much
There is one switch for the whole system, so turning it on for a browser also sends your company VPN client, your Steam downloads, your local development server and your NAS through the same proxy. Usually at least one of those breaks, and the bypass list is a blunt instrument for fixing it — it matches hosts, not applications.
2. It routes too little
The apps that ignore it are exactly the ones you often care most about, and they fail silently. Nothing warns you; the traffic simply leaves directly.
3. It cannot handle UDP
QUIC now carries a large share of ordinary web traffic, and games and calls have always been UDP. With a TCP-only setting, that traffic bypasses the proxy no matter what you configure.
When the built-in setting is enough
Be fair to it: if you want everything on your Mac to use one SOCKS5 proxy, your apps all honour the setting, and you do not care about UDP, the built-in setting is the right answer and you should stop here. It is free, it is already installed, and there is nothing to maintain.
When you need routing instead of a setting
The moment you find yourself wanting the word "only" — only this app, only this destination, only on this network — a single global switch cannot express it. That is a routing problem, and it has to be solved below the application, where the operating system still knows which process opened each connection.
ProxyRouter works at that layer. You point it at the same SOCKS5 upstream you would have typed into System Settings, then decide per application what happens:
- Apps you name use the proxy — including apps that would ignore the system setting entirely, because they are not asked.
- Everything else stays Direct, so the VPN, the LAN and localhost keep working.
- UDP is forwarded through SOCKS5 UDP ASSOCIATE, and QUIC becomes an explicit choice rather than a leak.
- Rules can be bound to a network, so the office set and the home set swap themselves.
Checking what is actually happening
Whichever route you take, verify rather than assume. Two quick checks catch most mistakes — the first shows whether the terminal is proxied, the second whether the browser is:
# what the terminal sees (respects env vars, not the system setting) curl -s https://api.ipify.org; echo # force the proxy for one request, to prove the upstream itself works curl -s --socks5-hostname 127.0.0.1:7890 https://api.ipify.org; echo
If those two print different addresses, your upstream works but the terminal is not using it — which is normal, and is covered on the terminal page linked below. In ProxyRouter, the Activity view answers the same question for every app at once: each connection shows the path it took and the rule that chose it.
FAQ
Where is the SOCKS proxy setting on macOS?
System Settings, then Network, pick the active service (Wi-Fi or Ethernet), Details, and the Proxies tab. Enable SOCKS Proxy and enter the host and port. The setting belongs to that one network service, so you configure it again for each Wi-Fi and each Ethernet adapter you use.
Why do some apps still connect directly?
Because the system proxy setting is advisory. macOS exposes it, and apps choose whether to read it. Anything with its own network stack — many Electron apps, Go and Rust binaries, Java tools, most games — never looks, and connects directly no matter what the setting says.
Does the macOS SOCKS setting proxy UDP?
No. It covers TCP only. Anything on UDP — QUIC and HTTP/3, game traffic, voice and video calls, DNS — goes out directly. That is the single most common reason a proxy appears to work in the browser while other things behave as though it is off.
Can I use a different SOCKS5 proxy for different apps?
Not with the built-in setting — there is one per network service, and it applies to everything that reads it. Per-app routing is a separate layer: ProxyRouter assigns each application its own upstream, so a browser, a terminal and a database client can each use a different one at the same time.
ProxyRouter comes with a free full-feature trial, no card required. You bring your own SOCKS5 or HTTP upstream — a corporate proxy, a staging gateway, or a port on localhost. We do not provide or resell proxy servers.