Shadowrocket for Mac · Official Guide
Shadowrocket User Guide
To get connected quickly, follow the quick-start guide. To switch devices, adjust rules, or troubleshoot, use the chapter list below. Chapter 1 covers getting and installing the app on each platform; the remaining instructions use the iPhone and iPad interface as examples.
01 / GET THE APP
Getting and installing the app
Check your device, download source, and app identity
Choose the download for your device. Get the iPhone / iPad version from the App Store product page for a one-time US$2.99 purchase. Both devices can use the same purchase; check the App Store page for system requirements. The Mac (Apple Silicon and Intel), Windows, Android, and Linux versions are free. Choose your device on the app download page; installers are distributed from this site at /dl/shadowrocket/. There are two ways to get the app; connection service details must be obtained separately.
On the store page, first verify the developer, Shadow Launch Technology Limited, then check the official icon and app ID 932747118 at the end of the product link. Search results with similar names may refer to different apps; the name and icon alone are not enough to verify the developer or app ID. If the page will not open, check whether the product is available in your account's storefront. When reinstalling, first check the purchase history for the original account. The store can confirm which account owns the purchase, but it cannot restore servers or rules previously saved in the app.
Mac: identify your chip, then drag the app to Applications
Open About This Mac from the Apple menu. If it shows a Chip entry with an M-series name, choose the Apple Silicon version in the Mac downloads section. If it shows an Intel processor, choose the Intel version. Use the chip in this Mac to select the installer—not the browser you're using or a filename saved on another computer. Open the downloaded disk image and drag Shadowrocket.app to Applications. When copying is complete, open the app from that folder. Eject the disk image only after the app has been copied. Dragging the image itself to the folder, or opening the app directly from the image, does not replace this step.
If macOS says it cannot verify the developer the first time you open the app, first check the download source and chip version. After confirming both, go to System Settings › Privacy & Security, find the record of this attempt, and follow the prompt to select Open Anyway. This option usually appears only after you have tried to open the app. If macOS says the file is damaged, the download was interrupted, or the architecture is incompatible, download it again and check the selected version; these are not routine first-open confirmation prompts. If the device is managed by an organization and the option is unavailable, ask the administrator for help rather than changing system-wide security settings.
Windows, Android, and Linux: install for your system
Choose the 64-bit installer for your device in the Windows downloads section, then run it from your Downloads folder. If SmartScreen appears, check the source and file. On a personal device, if appropriate, select More info and check whether Run anyway is available. If Windows explicitly reports a threat, stop the installation; do not treat a threat alert as a routine confirmation. After installation, launch the app from the system app list. Keep any installation error messages so you can distinguish a permissions issue from an actual installation failure.
Choose an installer that matches your device architecture in the Android downloads section. If Android asks you to allow the app that started the installation to install unknown apps, first confirm that the source is the browser or file manager you just used, then enable permission for that source only, as prompted. You can revoke it after installation. If the installer reports that the app is incompatible, check the device architecture, system message, and whether an app with the same name is already installed. Do not uninstall the version in use as a first step. If you do need to replace an installed version, back up any configuration you can export first.
Choose a package in the Linux downloads section based on your distribution and preferred installation method. On systems that use a package manager, choose the matching deb or rpm package. For an AppImage, grant the file execute permission in its properties, then open it from its directory. If the package manager reports missing dependencies, note the missing packages and distribution details instead of forcing the installation. If the system reports insufficient permissions, distinguish between a file without execute permission, a directory that does not allow execution, and an installation that requires administrator privileges.
02 / PERMISSIONS
First launch and VPN configuration permissions
Know where to start on Home
Open Shadowrocket on your iPhone or iPad and check four areas on Home: the connection switch shows the current connection state; Global Routing controls how traffic is routed; Connectivity Test checks the connection; and SERVER lists imported or manually added servers. The list may be empty right after installation, and Not Connected is normal. This screen does not create a server you can connect to. Make sure you have your own subscription or server details, then add them as described in the next chapter. For an overview of each section, see First launch and the Home screen.
The first time you launch the app or try to connect, iOS or iPadOS may ask to allow adding a VPN configuration. This system permission registers Shadowrocket's network configuration; it is not server authentication or a subscription password prompt. Start the action yourself in Shadowrocket, confirm that the request is for the correct app, then allow it in the system prompt. You may be asked for your device passcode or to authenticate with biometrics. After granting permission, return to Home and check the connection state there. Granting permission does not mean the proxy server is reachable or that traffic is being forwarded.
Think of this process as three separate checks: whether the system allows the configuration to be added, whether the app has a server selected, and whether the connection switch changes state. Each check addresses a different issue. For example, if permission is granted and the switch turns on but the server list is empty, add server details first. If a server is listed but the switch returns to Not Connected each time, check the system prompt and app status to see whether the system permission step is failing. Do not reinstall just because you see Not Connected, or repeatedly toggle multiple settings to try to pass a test.
Canceled permission requests, configuration conflicts, and managed devices
If you canceled the system prompt the first time, return to Home and start a connection attempt yourself to see whether the permission request appears again. If it does not and the action still fails, check VPN configurations in system Settings. The exact location varies by system version; you can search Settings for VPN. Check whether an existing entry belongs to Shadowrocket, whether another network configuration is running, and whether the device has management restrictions. Note the current state before making changes. Do not delete an unidentified VPN entry just to make a test pass.
Your device may also have a work- or school-managed VPN, a network filtering configuration, or an organizational policy that requires a connection to stay active. Even if Shadowrocket opens, the system may block adding or enabling a personal configuration. Note the step where access is blocked and the exact prompt, then ask the device administrator to check. If you already use another personal VPN, pause it only if you can safely disconnect it, then test again; restore it afterward if needed. This helps distinguish a conflict between configurations competing for the network path from incorrect server details.
If the connection turns off immediately after you allow the configuration, note the time, network, Home status, and system prompt, then follow the Connect and test chapter. If the app asks for camera access after permission was granted, first check whether you tapped Scan QR Code. Camera permission and VPN permission serve different purposes. If you do not want to enable the camera, enter the details manually or use an existing subscription. Grant permissions only after confirming the request matches the action you just started, and only when needed to complete that action.
03 / CONNECTION DETAILS
Add servers and import subscriptions
Understand servers, subscriptions, and Config
If your provider gives you the address, port, and authentication details for one server, add it manually with Add Server. If they provide a link that updates a group of servers over time, import it with Subscribe. Server details determine which upstream connection you can select; a subscription is a way to fetch and update those details. Config describes how traffic matches rules and which policies to use. These are different types of information. If you receive text in an unfamiliar format, ask your provider whether it is server details, a subscription, or a configuration instead of trying it in different fields.
Before entering details manually, select the protocol specified by your provider, then enter the server address, port, authentication fields, and required transport settings. The address is usually a hostname or IP; enter the port in its own field. Unless the field explicitly asks for a full URL, do not include a web scheme, port, or path in the host field. A remark helps identify the server; changing it does not fix network settings. After saving, return to SERVER and check the new entry. Confirm that it is selected before testing. If several entries have the same name, add clear remarks to distinguish them rather than deleting multiple entries.
Know which details each protocol requires
| Protocol | Check first | Fields that are easy to confuse |
|---|---|---|
| Shadowsocks | Address, port, encryption method, password | The encryption method must match the server; do not infer it from the password length |
| VMess / VLESS | Address, port, user ID, transport | The path, hostname, and service name used for verification may be different |
| Trojan / Hysteria2 | Address, port, authentication details, and applicable security settings | Use the fields for the specified protocol; do not substitute fields from another protocol |
| WireGuard | Local and peer configuration, keys, peer address | The local private key and peer public key are not interchangeable; never share the private key |
| HTTP / SOCKS5 | Proxy address, port, and any required authentication details | Whether a username and password are required depends on the proxy service |
The table helps distinguish fields; it does not mean protocols in the same group are interchangeable. The fields shown vary with the selected type and transport. Common mistakes include copying only the host and missing the destination port, or pasting a trailing space or line break. If the connection reports an identity verification failure, check the service name, device time, and provider's instructions; disabling verification is not a long-term fix. For an overview of how protocols handle transport and authentication, see Protocol overview.
Check imported details before updating
Get subscriptions from your service provider. Select Subscribe in the add menu, paste the complete original subscription URL, and save. Then check SERVER for the corresponding group and available servers. Query parameters after the question mark may identify your subscription access; removing them can invalidate the link. Do not post the full URL in public discussions or online checking tools. A QR code may also contain authentication details. Use Scan QR Code only when you trust the source, then check that the imported entries are what you expected before saving.
If a subscription saves but the list is empty, first check whether this is the only subscription affected. Look for a truncated URL, check whether the current network can reach the subscription, and ask whether your provider changed the link or service status. If the list is present but one server fails, test another known-good server in the same subscription and keep the original settings for comparison. If the subscription refreshes but connections still fail, check the selected server's protocol, password, or validity period. A successful refresh does not guarantee every server is usable. Conversely, a failed refresh does not necessarily affect servers already saved in the app.
Before the first refresh of a newly imported subscription, note the remark and group for the server currently in use. After refreshing, check for renamed, removed, or new entries. If the selected entry is gone, choose another server explicitly before testing. Maintain manually added servers separately from subscription-managed entries so you do not mistake a temporary change to one entry for a setting that will persist. If you receive a replacement link, verify its source, check the new link and entries, then remove the old one.
04 / ROUTING
The three Global Routing modes
Understand Config, Proxy, and Direct
Open Global Routing on Home and choose Config, Proxy, or Direct for your current purpose. Global Routing controls how the client handles connections it has taken over. SERVER selects the server used for the proxy route, while the connection switch determines whether the client establishes a network configuration. These work together, but they are not the same switch. Selecting a server while Global Routing is set to Direct does not send traffic through the proxy just because the server is highlighted. Switching Global Routing to Proxy will not fix incorrect server details.
| Mode | How connections are handled | When to use it |
|---|---|---|
| Config | Matches destinations against the current configuration's rules and applies the corresponding policy | Everyday routing; check whether a specific rule matches |
| Proxy | Traffic is handled by the currently selected proxy server | Briefly test the proxy path while minimizing the effect of rules |
| Direct | Taken-over traffic uses a direct path, bypassing the selected proxy server | Set up a direct-path comparison; test separately from turning off the client |
Config is both a routing option on Home and the name of the configuration management screen. The distinction is that the configuration screen lets you manage and select a configuration, while choosing Config on Home tells the client to handle traffic using the configuration currently in effect. Doing the first alone does not change the current global routing mode; doing the second alone does not automatically switch to a newly imported file. When troubleshooting a rule, note the active configuration name, Global Routing mode, and current server so you do not look in the wrong file.
Check rule order and the default policy
Common routing rules are evaluated from top to bottom. Put narrower exceptions first, broader rules later, and use FINAL for connections that did not match anything above. DOMAIN matches an exact hostname; DOMAIN-SUFFIX covers a domain and its subdomains; DOMAIN-KEYWORD matches a keyword and has broader reach, so check that it does not include unrelated domains. Domain rules take a hostname, not a URL with a scheme, path, or query parameters. Services often use multiple domains, so being able to reach the home page does not mean that login, image, or upload requests matched the same rule.
IP-CIDR and IP-CIDR6 match IPv4 and IPv6 address ranges, respectively. GEOIP matches the region associated with the destination IP, not the user's location or interface language. When matching IPs, check whether the resolved address is usable and whether the same domain resolves to different destinations on different networks. PROXY, DIRECT, and REJECT are policies applied after a match: use a proxy, connect directly, or reject the connection. When domain and IP rules are mixed, order them by the conditions you want to match first, not just alphabetically or by rule type.
[Rule]
DOMAIN,static.example.com,DIRECT
DOMAIN-SUFFIX,example.com,PROXY
GEOIP,CN,DIRECT
FINAL,PROXY
In this .conf example, static.example.com matches the exact rule first and uses DIRECT. Another subdomain of example.com matches the suffix rule below and uses PROXY. If you reverse the order, the suffix rule may catch the exact exception first. The last line makes PROXY the default for remaining traffic, which may not suit every setup. When adding this snippet to an existing configuration, make a backup, choose where to insert it in the existing [Rule] section, and confirm that only the intended fallback logic remains at the end. Do not replace the entire existing file with the snippet.
When testing a change, start a new connection rather than relying on a page that is already loaded or reusing a connection. First test a destination that should connect directly, then one that should use a proxy, and finally a destination outside the changed rules to check that the default behavior has not changed unexpectedly. If Proxy works but Config fails, check rule order, DNS results, and the configuration in use. For more examples, see Rule syntax and matching order.
05 / TESTING
Connect and troubleshoot step by step
Confirm the network works before testing the proxy
Before you start, confirm that the device can make ordinary network requests with Shadowrocket disconnected. If the Wi-Fi network has a sign-in page, complete the login as instructed by the network provider. If the device is switching from Wi-Fi to cellular, wait for the connection to stabilize. Choose a familiar destination you can normally reach as a control, and note the device's underlying network. This helps you tell whether the basic network is down or only the proxy or routing path is failing. Do not change networks, switch servers, and edit rules all in the same comparison test.
Return to Home, select a server with complete, known details under SERVER, and check Global Routing. Turn on the connection and wait for the status to stabilize, then run Connectivity Test. One test tells you whether a particular request succeeded under the network and configuration in use at that moment; it cannot prove that all apps and websites work. Response times from different test destinations are not directly comparable. Next, make a new request in a browser or target app. If only an old page seems to work, refresh it or make a new request so cached content is not mistaken for a successful connection.
If the status is Connected but the test fails, do not immediately assume system permission is the problem. Connected means the client has established a connection state; it does not guarantee that the selected server completed a remote handshake, that DNS resolution worked, or that the destination service is available. Conversely, a site failing to load in a browser does not mean the entire connection is down: the destination may be unavailable, or the site's multiple domains may be handled by different rules. Try another known-good control destination, check the time and status, then decide whether to troubleshoot the network or the rules.
Change one variable at a time based on the symptoms
If ordinary network access also fails when the connection is off, troubleshoot the device's internet connection first. If the control destination works without a proxy but multiple destinations fail in Proxy mode, check that the correct server is selected, its address and port are correct, and the current network can reach it. Try another known-good server from the same subscription without changing encryption or authentication details at the same time. If multiple servers fail on the same network, repeat the test on another available network to see whether the issue follows the network.
If Proxy can reach the destination but Config cannot, check whether the active configuration has an earlier broad match, REJECT, or a FINAL policy that differs from what you expect. If Direct works but Config fails, that alone does not identify the faulty rule. Check whether the matched domain is the one in the page address; where needed, check other domains the app connects to separately. After a test in a temporary mode, restore your usual Global Routing setting and repeat a key request so the temporary choice is not left in place for everyday use.
For intermittent disconnects, note whether the device was locked, had just switched from Wi-Fi to cellular, or had just refreshed a subscription. After a network switch, an existing connection may need to be re-established; check whether a new request works instead of repeatedly toggling the switch. If the same server is stable on a fixed network but fails during automatic transitions, check On Demand, system network status, and whether the app retries. If the issue is hard to reproduce, record both a successful scenario and a failing one; this is usually more useful than keeping only an error screenshot.
06 / TRAFFIC
Read Data traffic records
Understand what the data covers
Data shows traffic recorded by the client. First check the time range, item being measured, and units shown on the screen, then look at the values. Note a starting value, perform one action, and compare the increase rather than focusing only on the total. Upload and download refer to the sending and receiving directions. Uploading a file mainly increases sent traffic; browsing images or video mainly increases received traffic. Web interactions, syncing, and protocol handshakes can still generate traffic in both directions.
Cellular data usage in the device's system settings, your provider's usage records, and Data are not the same ledger. They are recorded at different points, may use different billing periods, and may count protocol overhead, retransmissions, or activity from other apps differently. Usage distribution changes when you switch networks, but that does not automatically reset the client's accumulated records. For your plan usage, use your provider's billing period and measurement method. To check how much cellular data the device used, consult the system's own records.
Distinguish a total from a rate: a total describes how much data was transferred over a period; a rate describes how fast it was transferred at a particular time. A file's listed size may not match the increase from one action because of caching, compression, retries, and background syncing. Different devices do not necessarily share a counter. For example, do not assume that content viewed on an iPad is included in the Data value on an iPhone just because both use the same subscription.
Compare before and after to observe one action
To check whether a request generated traffic, stop unnecessary downloads and note the current total, network type, Global Routing mode, and server remark. Then perform one action, such as opening a page that has not been loaded before. Wait for it to finish, then check Data for a change. If you cannot see a difference, check the display precision and refresh timing, and whether the content was already cached. A few small tests under the same conditions usually reveal more than a large change after altering several settings at once.
To compare behavior in Config and Proxy, keep the server and underlying network the same, and make new requests for content of roughly similar size. Do not repeatedly open the same cached resource; a smaller increase the second time may have nothing to do with routing. If the screen offers more detailed categories, check what each category means before comparing values by direction and range. If only a total is shown, an increase is evidence that data was transferred, not proof that a particular domain matched PROXY or DIRECT. Check the rules and connection tests to confirm that.
Troubleshoot unexpected spikes or unchanged records
If the value jumps unexpectedly, note when it happened and check whether video playback, file syncing, an app update, or a background restore just started. Compare the change after stopping that task. If the record does not change, confirm that the connection is still on, the screen has refreshed, and the request was not served from a local cache. If access itself is failing, check basic connectivity and routing as described in the previous chapter rather than clearing the statistics. Save any useful comparison data before clearing records. When comparing afterward, note the start and end points; resetting a counter does not mean traffic has disappeared.
Keep only useful troubleshooting notes, such as the action, network, and approximate before-and-after difference. Separate short observations used to isolate one behavior from longer-term usage checks; the latter require consistent dates, devices, and measurement methods. Before sharing a screenshot or notes, hide identifiable addresses, connection names, subscription details, and personal network identifiers. This preserves useful clues without exposing configuration details to people who do not need them.
07 / SETTINGS
Common Settings and automatic connections
Establish a manual baseline before enabling On Demand
On Demand lets the system trigger a connection under specified conditions. Global Routing determines how requests are handled after the connection is established. Automatic triggers do not select a better server or rewrite rules; if a manual connection does not work, enabling On Demand usually makes the issue occur more often. First verify the manual connection and Config routing on a network you use regularly. Then find On Demand in Settings and choose the conditions you need. Test both scenarios where it should trigger and where it should not.
If Settings offers conditions for Wi-Fi or cellular networks, start with one scenario and note the original value. Then have the device make a real network transition. Give the system time to recognize the new network state, return to Home, and check the connection. Make a new, lightweight request to confirm it works. An open page that still responds to an old request does not necessarily mean automatic connection was triggered on the new network. If some scenarios should not connect automatically, test those too; repeatedly toggling the switch on one network is not a substitute for checking the conditions.
If you turn off the connection manually but it comes back on, first check whether On Demand conditions are still being met. For troubleshooting, pause the relevant trigger conditions before disconnecting. Restore them as recorded when testing is complete. If a system-managed configuration controls the switch or an organization policy determines automatic connections, do not try to override it as if it were an app preference. On devices that switch networks often, first test recovery after locking the screen and after a network transition, then keep automatic connection enabled for everyday use if appropriate.
Change DNS and test settings only to address a specific issue
DNS resolution provides a destination address; it is a separate layer from whether the proxy server is reachable. If only some domains fail or the same rule behaves differently on different networks, first check whether DNS behavior follows the active configuration and whether the system or network also provides its own resolution. Changing DNS may return a different IPv4 or IPv6 address for the same domain, affecting rules such as GEOIP and IP-CIDR. Note the original setting, change one thing at a time, and retest the same destination on the same network. Do not change resolution, switch servers, and reorder rules all at once.
If the interface lets you choose the Connectivity Test target or method, use a reliable target suited to comparison. Changing the test target should make results easier to interpret, not make a timeout look better. If one target suddenly fails, check whether it is reachable before concluding that the server has a problem. After switching test methods, the old and new results may measure different network paths, so their numbers cannot directly show whether the server is faster or slower. Record the test conditions; a number without context is less useful when reviewing the issue.
Distinguish app settings, configuration files, and server details
Before changing anything, identify which layer the setting belongs to. Check general behavior in Settings, routing rules in the active Config, and connection-specific protocol details in the relevant SERVER entry. Layouts and available options may differ across devices; do not replace an entire configuration just because you cannot find a particular item. Permission prompts also have distinct purposes: scanning a QR code requires camera access, while a system VPN configuration establishes the connection. Neither permission can fix an address, authentication, or rule error.
For each change, note the original value, new value, reason, and test result. Make a restorable copy before important changes, and give test configurations a different name from the one you use every day. If the change does not help, revert it before trying something else, so temporary changes do not interfere with one another. If an update moves an item, look for its English name and purpose instead of blindly tapping coordinates from an old screenshot. You can also consult Settings guide and the interface terms reference.
08 / MAINTENANCE
Updates, migration, and recovery
Update the app, subscriptions, and rules separately
App updates, subscription refreshes, and rule changes serve different purposes. An app update may change the interface or implementation; refreshing a subscription mainly changes the server list maintained by your provider; editing Config may change which requests use a proxy or connect directly. Avoid changing all three in one maintenance session. First record a working state, then make and verify one change at a time. If something goes wrong, you can roll back or review the latest change instead of trying all three and losing track of what caused the problem.
Check installed apps and updates for iPhone and iPad in the App Store. For Mac, Windows, Android, and Linux, use the app download page to get the installer for your platform from this site. Before updating a Mac, still check whether you need the Apple Silicon or Intel version. On Linux, confirm whether you are keeping the same package format or switching to another. Do not treat a change of architecture or package format as a routine in-place update. If a new system compatibility prompt appears, understand what it means and back up your configuration before installing or updating in the usual way for your device.
Before refreshing a subscription, note the selected server and group. Afterward, check that key entries are still available for selection. If an old server has been removed, choose a server from the current list with known, complete details and test it again. Keep a restorable copy of your configuration and make rule changes in a copy first. If Config is the only mode that fails, switch back to the most recent working copy for comparison. Choose maintenance actions based on the identified problem: check the installation if the app will not start, the subscription if the list changes, and the rules if matching is wrong.
Prepare the information you can restore before switching devices
Before switching devices or reinstalling, note the name of the active configuration, where to get your subscription again, whether you have manually entered servers, and which On Demand conditions are in use. Keep copies of important information using the export or backup options in the interface, and make sure the files can be found and read on the target device. Subscription URLs, authentication details, and private keys may allow others to use your connection; store copies somewhere accessible only to you or people you trust. Screenshots can help you remember the interface, but they cannot replace configuration files or complete connection details.
During migration, restore the app and configuration separately. Use the original purchase account to restore the app on an iPhone or iPad, then confirm it opens and grant system permissions before restoring subscriptions, manually added servers, and configurations one by one. If the app appears but the configuration list is empty, that does not mean the purchase failed; restore from your backup or information from your service provider. Before connecting the new device, confirm the old one can still return to a working state. After verifying a manual connection, key rules, and automatic connections on the new device, decide whether to remove credentials and backups from the old one.
Keep a minimal working setup and retest checklist
If you cannot identify what caused a regression, return to one known-good server, a verified configuration, and manual connection mode. Test in order: whether the system can establish a connection, whether the proxy path can handle a control request, and whether Config can match expected direct and proxy rules. This sequence gives you separate checkpoints for system permissions, the server, and routing. Once the baseline works, restore subscription refresh, other rules, and On Demand one at a time. If the issue returns, start troubleshooting from the step where it reappears.
For routine checks, retest a few key scenarios: one familiar Wi-Fi network and one cellular network, a destination expected to connect directly, one expected to use a proxy, and any automatic connection conditions you rely on. When an issue recurs, note when it happened, what triggered it, and the last step that clearly worked. Do not include a complete subscription or authentication details. To repeat the setup from the beginning, return to the quick-start guide. If you know which step fails, continue with the matching symptoms in Troubleshooting.