# ShadowsocksX-NG: a macOS Shadowsocks client that runs ss-local as a launchd service > ShadowsocksX-NG is a Swift GUI wrapper for shadowsocks-libev on macOS, with SIP003 plugin support and PAC rules. The last push to the repository was on 2024-10-29, so treat it as a finished tool rather than a moving target. **shadowsocks/ShadowsocksX-NG** — GitHub describes it as Next Generation of ShadowsocksX. The repository metadata lists Swift as its primary language. The metadata lists the GPL-3.0 license. This article stays within the project description and details documented in the GitHub repository README. - Repository: https://github.com/shadowsocks/ShadowsocksX-NG - Stars: 32,878 · Forks: 7,744 - Language: Swift - License: GPL-3.0 - Published: 2026-08-13 · Updated: 2026-08-18 · Language: en - Canonical page: https://hysenlabs.com/projects/shadowsocks-shadowsocksx-ng ## The problem ShadowsocksX-NG solves for macOS users Running a Shadowsocks client on macOS means two separate jobs: keeping an ss-local process alive, and pointing the operating system's proxy settings at it. The README explains why the original ShadowsocksX was hard to maintain: it embedded the ss-local source code, so updating the client meant updating a dependency tree inside the app. ShadowsocksX-NG takes the opposite approach. It copies the ss-local binary from Homebrew and runs it as a Launch Agent, leaving only GUI code in the repository. That decision is the whole project. The app is a control surface for a binary it does not compile, and the README states the GUI was rewritten in Swift. The audience is narrow and clear: people on macOS 10.12 or newer who already have a Shadowsocks server and want a menu bar client rather than a command-line process they manage by hand. If you do not have a server, this project gives you nothing to connect to. The README lists no server setup, no subscription service and no hosted offering. ## How the launchd split changes day-to-day behaviour In the original ShadowsocksX, ss-local ran as an in-app process. In ShadowsocksX-NG, according to the README, ss-local is run as a background service through launchd, not as an in-app process. The README is explicit about the consequence: after you quit the app, ss-local might still be running. That is a real difference in behaviour, not a detail. Quitting the menu bar app does not necessarily stop your proxy, and the documentation does not describe a separate command for stopping the Launch Agent. The app also adds a manual mode that does not configure the system proxy settings, so you can point individual applications at the SOCKS5 proxy yourself. Between those two modes you get a choice: let the app rewrite system proxy settings, or leave the system alone and configure each app. The README does not document what happens to in-flight connections when you switch modes, and it does not document rollback if a proxy setting is left behind. ## Installing ShadowsocksX-NG and making a first connection The README points to the GitHub releases page for downloads; there is no Homebrew cask or package manager command in the README. Download the latest release and move the app to Applications. The README states macOS 10.12 or newer is required. ```bash # The README links to the releases page for downloads: # https://github.com/shadowsocks/ShadowsocksX-NG/releases/latest ``` After launching, add a server profile. The README lists several ways to do this: import a server profile URL from the pasteboard, scan a QR code on screen, or share profiles by QR code or URL. Once a profile exists, the app can update PAC by downloading the GFW List from GitHub, and it supports custom rules for PAC. The README also notes AEAD cipher support and HTTP proxy through privoxy. Building from source is a separate path and needs Xcode 12.5.1 or newer plus CocoaPods 1.10.1 or newer. The repository Makefile defines debug and release targets that call xcodebuild against ShadowsocksX-NG.xcworkspace, and a deps/dist target that runs make in the deps directory first. ```bash make debug make release make debug-dmg ``` The debug and release targets build into a local build directory using SYMROOT set to the current working directory. The dmg targets package the built app with a symlink to /Applications and create a disk image with hdiutil. A VERSION variable defaults to 0.0.0 and is applied through agvtool, so an unversioned make run produces a build marked 0.0.0. ## SIP003 plugins and what the bundled binaries commit you to The README states the app embeds kcptun, simple-obfs and v2ray-plugin, and supports SIP003 plugins. That is more than a feature list; it fixes a set of plugin binaries inside the app bundle. The bundled ss-local comes from shadowsocks-libev 3.2.5, per the README. When you install a release, you are adopting that libev version and those plugin builds together. Upgrading one without the other is not something the README describes. This matters if your server expects a newer plugin protocol or a cipher the bundled ss-local does not implement. The README does not list a supported cipher set beyond the AEAD link, so the practical check is your server's configuration against the client's. The HTTP proxy path goes through privoxy, which the README names as the mechanism rather than describing configuration for it. ## Where ShadowsocksX-NG is the wrong tool Three cases stand out. First, non-macOS platforms: the README states macOS 10.12+ for running, and the repository is a Swift Xcode project with CocoaPods, so there is no Windows or Linux client here. Second, anyone who wants a client that tracks upstream shadowsocks-libev: the bundled ss-local is pinned at 3.2.5 in the README, and the last push to the repository was on 2024-10-29, with the most recent release v1.10.3 on the same date. The previous release, v1.10.2, was on 2023-03-29, which shows the release cadence is not continuous. Third, users who need a documented lifecycle: the README does not document rollback, does not describe how to stop the launchd service after quitting the app, and does not state a support policy. If your environment requires a maintained client with a published update path, this project does not provide one. It is also not a server. Nothing in the README helps you deploy or operate a Shadowsocks endpoint. ## Alternatives and the real difference in approach The closest comparison is the original ShadowsocksX, from which this project forked. The README describes the split directly: the original embedded ss-local source code and carried a large amount of unused code, which made updating the client's ss-local version difficult. ShadowsocksX-NG runs ss-local as a launchd service and keeps only GUI code in the repository. That is the trade: you get a client that can be updated by swapping a binary, and you accept a background process that outlives the app. A second alternative is running shadowsocks-libev directly. The README says ss-local is copied from Homebrew, so the same binary is available without this GUI. You would manage the process and system proxy settings yourself, and you would lose the menu bar controls, QR code import, and PAC rule management the README lists. A third is any client built around a different core, such as shadowsocks-rust or shadowsocks-go. Those are different implementations with their own release cycles; the README does not compare their behaviour to libev, so the honest statement is that choosing them means leaving the ss-local 3.2.5 bundle behind, not that one is faster. ## Maintenance status, licence and upgrade cost The repository is not archived, but the last push was on 2024-10-29, which is the same date as the v1.10.3 release. The release before that, v1.10.2, landed on 2023-03-29. On that evidence, treat the project as stable and slow-moving rather than actively developed. The practical upgrade cost is low if you install from releases: replace the app, and the bundled ss-local and plugins come with it. Building from source is heavier. You need Xcode 12.5.1 or newer and CocoaPods 1.10.1 or newer, the Podfile and Podfile.lock are checked in, and the Makefile's deps target builds the dependency tree before xcodebuild runs. The licence is GPL-3.0, stated in the README and present as a LICENSE file at the repository root. GPL-3.0 is a copyleft licence; if you redistribute a modified build, the obligations attach to your distribution. That is a description of the licence text, not legal advice, and anyone bundling this into a product should read the licence themselves. Contributions, per the README, must go on a separately named branch based on develop. ## Conclusion Adopt ShadowsocksX-NG if you are on macOS 10.12 or newer, you already have a Shadowsocks server, and you want a menu bar client that manages system proxy settings and PAC rules for you. Skip it if you need a cross-platform client, a Windows or Linux build, or a project that receives regular commits; the last push was on 2024-10-29 and the README does not document rollback or a support policy. Before installing, verify that the release you download matches your macOS version, that your server uses a cipher the bundled ss-local 3.2.5 supports, and that you are comfortable with a launchd agent that keeps running after you quit the app. ## FAQ ### How do I use ShadowsocksX-NG? Download a release from the GitHub releases page and open the app on macOS 10.12 or newer. Add a server profile by importing a URL from the pasteboard or scanning a QR code, then either let the app configure system proxy settings or use manual mode and point individual apps at the SOCKS5 proxy. ### Is Shadowsocks safe to use? The README does not make security claims about the protocol or the client. It states the bundled ss-local comes from shadowsocks-libev 3.2.5, that the app supports AEAD ciphers, and that it is released under GPL-3.0. Safety depends on your server configuration and the cipher you choose, neither of which the README documents. ### Can Shadowsocks be detected? The README does not discuss detection or traffic analysis. It lists SIP003 plugin support and embeds kcptun, simple-obfs and v2ray-plugin, which are the components commonly used to shape traffic, but it makes no claim about whether a given setup is detectable. ### What is Shadowsocks and what is its purpose? The README treats Shadowsocks as the protocol the client speaks and does not define it. ShadowsocksX-NG's stated purpose is to provide a macOS GUI that runs the ss-local binary as a launchd service and manages proxy settings, PAC rules and server profiles around it. ### Does Shadowsocks still work in China? The README does not address reachability or network conditions in any region. It documents the client's own features, such as SIP003 plugin support, PAC updates from the GFW List, and AEAD ciphers, and leaves any judgement about whether a given deployment works to the user. ## Sources - [Official README](https://github.com/shadowsocks/ShadowsocksX-NG#readme) - [Project repository](https://github.com/shadowsocks/ShadowsocksX-NG) - [Release notes](https://github.com/shadowsocks/ShadowsocksX-NG/releases) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/shadowsocks-shadowsocksx-ng