ShadowsocksX-NG: Shadowsocks GUI for macOS
/ShadowsocksX-NG
ShadowsocksX-NG is a native Swift menu-bar app that wraps the ss-local binary from shadowsocks-libev in a macOS GUI, handling PAC rules, server profiles, and SIP003 plugins so you're not hand-editing a config file. It's worth installing once you already run Shadowsocks servers and want profile switching from the menu bar instead of a terminal session. The catch: ss-local keeps running under launchd even after you quit the app.
What is ShadowsocksX-NG?
ShadowsocksX-NG is the Swift-rewritten successor to the original ShadowsocksX, a macOS menu-bar client for the Shadowsocks proxy protocol. It runs the shadowsocks-libev ss-local binary as a background Launch Agent under launchd rather than embedding a custom build, then layers a GUI on top for server profiles, PAC rules, and system proxy settings. The rewrite trimmed the unused code that made updating ss-local painful.
Core features: plugins, PAC, and server management
- ✓ss-local sourced from shadowsocks-libev 3.2.5, run as a launchd background service rather than bundled in-process
- ✓SIP003 plugin support with kcptun, simple-obfs, and v2ray-plugin embedded
- ✓PAC updates by pulling the GFW List straight from GitHub, plus custom PAC rules
- ✓Server profile sharing via QR code or URL, including importing a profile by scanning a QR code shown on screen
- ✓Import server profile URLs straight from the clipboard
- ✓AEAD cipher support per the shadowsocks.org spec
- ✓Bundled HTTP proxy through privoxy
- ✓Manual mode that skips system proxy configuration so you can point individual apps at the SOCKS5 proxy yourself
Strengths
- ✓Ships prebuilt kcptun, simple-obfs, and v2ray-plugin, so SIP003 plugin traffic obfuscation works without hunting down separate binaries
- ✓PAC rules pull straight from the GFW List on GitHub, so split-tunneling stays current with a refresh instead of a hand-edited rule file
- ✓Profile sharing via QR code or URL makes moving a server config to another Mac fast
- ✓Manual mode lets you skip system-wide proxy changes and point individual apps at the SOCKS5 proxy yourself
- ✓Runs ss-local from shadowsocks-libev 3.2.5 rather than a custom fork, so it inherits upstream fixes instead of a maintainer-patched version
Limitations & risks
- △ss-local runs as a launchd background service, so quitting the app does not stop the proxy — you have to notice that and stop it separately
- △Building from source needs Xcode 12.5.1+ and CocoaPods 1.10.1+, a heavier setup than grabbing a prebuilt release
- △It's a client only — you still need a Shadowsocks server to connect to, ShadowsocksX-NG doesn't provide one
- △The README doesn't document uninstall steps or how to fully kill the background ss-local process, so cleanup is on you
Alternative macOS proxy clients
Frequently asked questions
The README points to the GitHub releases page for prebuilt downloads; installation itself isn't walked through step by step beyond grabbing the latest release. Building from source instead requires Xcode 12.5.1+ and CocoaPods 1.10.1+, and ShadowsocksX-NG needs macOS 10.12 or later to run.
ShadowsocksX-NG embeds both v2ray-plugin and kcptun directly, alongside simple-obfs, as SIP003 plugins, so no separate plugin install is needed.
Quitting ShadowsocksX-NG does not stop the proxy. The underlying ss-local process runs as a launchd background service (a Launch Agent), separate from the app's own process, so it can keep running after you close the GUI.
ShadowsocksX-NG supports SIP003 plugins and ships with kcptun, simple-obfs, and v2ray-plugin embedded, so you can enable them from within the app rather than installing separate plugin binaries.
ShadowsocksX-NG is released under the GPL-3.0 license and its source code is hosted publicly on GitHub, making it free to use, inspect, and modify.
ShadowsocksX-NG requires macOS 10.12 (Sierra) or later to run, per the project's stated requirements; building it from source separately requires Xcode 12.5.1+.
The problem it solves
Setting up Shadowsocks on macOS by hand means compiling or installing ss-local yourself, hand-editing a JSON config for each server, and separately maintaining PAC rules or a GFW list so only blocked traffic gets proxied. ShadowsocksX-NG folds that into a menu-bar app: profiles, PAC updates, and plugin config live in a GUI instead of scattered config files and a background process you start manually.
Best use cases
- •Switching between multiple Shadowsocks server profiles from the menu bar without editing JSON config files by hand
- •Running a SIP003 plugin like v2ray-plugin or kcptun to obfuscate traffic on networks that block plain Shadowsocks
- •Keeping a PAC-based split-tunnel setup current by pulling GFW List updates instead of maintaining a static rule file
- •Sharing a server profile with another Mac by generating a QR code or URL instead of retyping connection details
- •Manually routing specific apps through the local SOCKS5 proxy using manual mode when you don't want a system-wide proxy
How to install / try
ShadowsocksX-NG ships as a prebuilt release on the project's GitHub releases page — download the latest build and run it; the README doesn't walk through the install dialog itself beyond that link. Building from source requires Xcode 12.5.1+ and CocoaPods 1.10.1+, and the compiled app needs macOS 10.12 or later to run. Contributors are asked to branch off `develop` following the GitFlow model rather than committing straight to main.
Who should try it — and who should skip
ShadowsocksX-NG fits macOS users who already have a Shadowsocks server and want profile switching, PAC updates, and SIP003 plugins in a menu-bar app instead of a terminal and a JSON file. Skip it if you don't run Shadowsocks servers at all — this is a client, not a VPN service — or if you need a proxy protocol outside Shadowsocks/SIP003, since the app doesn't speak VMess, Trojan, or similar protocols on its own.
Related repositories
Is ShadowsocksX-NG worth your time?
ChatGPT, Claude and Perplexity can all read this page. Ask one of them what it makes of ShadowsocksX-NG.