Shadowrocket
Subscriptions and Servers
Management Guide

01 / Identify the Input

Subscribe: Import an Existing Subscription

A subscription link points to an updatable list of servers; it is not the connection address for a single server. After import, Shadowrocket requests the link, reads content it can recognize, and creates server entries. If names, server counts, or connection parameters change in the list, you need to update it to reflect those changes locally. Before you begin, make sure you have the complete subscription URL—not an account page, an information page, or a single server's sharing text.

Check the Link's Purpose and Sensitive Parts

Get your existing subscription link from your provider and keep the original text intact. Don't reformat it in a messaging app or remove a long-looking string of characters at the end. Content after a question mark may identify your account, and the path itself may contain access credentials. A link opening in a browser does not necessarily mean it points to a server list the app can read. If it opens a sign-in page, confirm what the link is for; don't enter your account password in the server's Password field.

The example below shows the general appearance of a URL and cannot be used to connect. Its domain and parameters are fictitious. Keep real links only on your own devices and in backups you control. Don't include them in support screenshots, public notes, or shared photo libraries. Even a partially exposed link may reveal enough information to grant access.

https://example.com/sub?token=xxxx

Open Subscribe from Add Server

Open the add menu from Home, go to Add Server, check Type, and select Subscribe. Enter the complete subscription URL in the URL field. Add a note that identifies the subscription, check for spaces or line breaks at either end of the address, then save. The layout may vary by device or app version. Look for the English labels Type and Subscribe rather than relying on a button's exact screen position.

After saving, return to Home and check the subscription group and its server entries. A successful import means the list contains selectable servers, not just a note. If you see a subscription entry but no servers, first check whether the URL is reachable over your network, then whether its response uses a recognized format. Don't immediately add the same URL again; that can turn one failed request into several duplicate groups.

Treat List Updates and Connections Separately

A successful list request means the subscription was retrieved and parsed; it does not prove that every server can connect. Conversely, servers already saved locally may still work when an update fails. Troubleshoot these as separate questions: “Can the subscription update?” and “Can an existing entry connect?” Don't use one result as a substitute for the other. After selecting a server, also check Global Routing and the connection switch. For the first-connection steps, see Getting Started.

If the same URL has already been imported, update the existing subscription instead of adding another copy. This keeps its source clear and makes it easier to identify changes caused by an update. If you're unsure whether an entry belongs to a subscription or was added manually, check its group and edit details before changing it. Expect local edits to subscription entries to be overwritten by a later update.

02 / Match the Fields

Add Server: Enter Server Details Manually

Manual setup is for cases where you already have complete server details and need to check them field by field. Choose Type first, then fill in the fields required for that type. The protocol determines how the client communicates with the server; don't switch types just because another one has fewer fields. Address, Port, and Password are common fields, but some types also require an identity, encryption method, transport settings, or TLS options. Missing any of these can prevent a connection.

Choose Type Before Checking Basic Fields

Open the add menu from Home, then set Type in Add Server to the protocol used by your server. Enter Address and Port from the original details. Address is usually a hostname or IP address; don't include a web path, username, or extra spaces. Port is a separate number, so don't repeat the port after a colon in Address. Unless a field explicitly asks for a complete URL, don't enter the entire sharing link as the host address.

Password must match the server you're setting up; your app purchase account password is not a substitute. If you need to verify a copied value, check its first and last characters and capitalization in a private setting. Don't use a public screenshot. For protocols that use identity fields such as UUID, enter those in the corresponding fields rather than putting all authentication details in Password. A note is only for identification; changing it won't fix incorrect credentials.

Protocol Parameters Are Not Interchangeable

The Shadowsocks encryption method must match the server. For VMess, VLESS, and other types, check identity fields and transport settings against the original details. Trojan authentication and TLS settings cannot be inferred from its name. HTTP, SOCKS5, WireGuard, and Hysteria2 each have their own parameter structure. There is no universal set of defaults: settings that work for one server may not work for another. If the original details are incomplete, get the missing information before proceeding.

If the server requires TLS, distinguish the connection destination from the name used for certificate verification. Address determines where to connect; a related name field may be used during the TLS handshake. They are not necessarily the same. Transport fields such as Host and Path may also serve different purposes, so don't substitute them just because their names seem similar. For certificate errors, check the device time, hostname, and original settings first. Don't weaken verification to hide an input problem.

Save and Test One Variable at a Time

After saving, return to Home and make sure the newly added server is selected, not an older entry with a similar name. Run a connection test, then try a destination you are already authorized to access while connected. If it fails, change one parameter at a time and note the results before and after. Changing the protocol, port, and transport settings all at once makes it hard to identify the cause—even if the connection later works—and risks repeating the problem next time.

Avoid relying on manual edits to maintain subscription entries over time. If you need to compare a parameter, create a separate test entry only if the app supports it, and clearly label its purpose so it isn't confused with the original subscription entry. After testing, keep an accurate record of the original parameters. For app access or first-time VPN configuration permission, see How to Get Shadowrocket on iPhone; don't mistake a system permission issue for a server field problem.

03 / Review Before Saving

Importing with a QR Code or Clipboard

QR code and clipboard imports reduce manual entry, but they don't determine whether a server suits your current network or fill in missing parameters. Follow the same steps for both: confirm the content belongs to your own server or subscription, review the parsed result, check key fields, then save and test. “Recognized” does not mean “correctly configured.” Don't overwrite an existing entry just because a QR code scanned successfully.

Steps for Using Scan QR Code

Prepare a QR code for a server or subscription you already have. In Shadowrocket, open Scan QR Code and allow camera access if prompted. Fit the entire code in view, avoiding glare, obstruction, or an image displayed too small. After it is recognized, review the result. For a single server, check Type, Address, and Port; for a subscription, check URL and the note. Save only after confirming the result matches the original details.

If a QR code is blurry, get a clearer original image or the original text rather than repeatedly zooming and taking new screenshots. Compression can destroy details needed for recognition, and low screen brightness or glare can also interfere. If the code is on the same device, check whether the current screen offers an option to read an image. If not, you can import the original text instead; there is no need to skip content checks just to scan the code.

Keep Clipboard Imports to One Clear Input

Select only the complete sharing text when copying. Don't include explanatory text, chat timestamps, numbering, or punctuation at the end of a sentence. Return to Shadowrocket and use the clipboard import option shown in the current interface. Follow the system prompt to allow pasting. If a preview appears, confirm whether it represents a subscription or a server and check the fields. A prompt asking permission to paste controls clipboard access; it is not a server connection request and does not mean a VPN connection has been established.

Pasting several lines may produce a different result from importing a single link. For your first import, try one entry and confirm the format is recognized correctly before processing the rest. If the number of imported entries looks wrong, check the original text for duplicate links, titles, or URLs split by line breaks. Don't keep pasting the same content; that usually adds similar entries rather than fixing a formatting problem.

Troubleshoot Permissions, Recognition, and Connections Separately

If the camera won't open, check Shadowrocket's camera permission on your device. If the camera opens but recognition fails, check the QR code's clarity and content format. If recognition succeeds but the connection fails, check the server parameters and network. These are separate stages with different causes. Clipboard imports work the same way: being unable to read text after denying paste permission is a permissions issue; reading it without creating an entry is a parsing issue; a failed test after saving is a connection issue.

After importing, replace the clipboard contents with ordinary text that contains no sensitive information to reduce the risk of pasting it by mistake later. If you shared the QR code as a screenshot, check whether the image was saved to a shared photo library or a publicly synced location. Deleting the image does not invalidate the credentials. If you confirm the content was exposed, replace the affected credentials through the relevant service's management tools, then update your device.

Whether you import by QR code or another method, use the same checks: review the group, type, and destination address, then select the entry and test it. If the interface is unfamiliar, see A Guide to the Home Screen. This helps distinguish import issues from selecting the wrong server on Home, especially when entries have similar names.

04 / A Link Is Not a Complete Configuration

Sharing Link Formats and Config Boundaries

A sharing link encodes server parameters as text that can be passed to someone else. A subscription URL points to a list that may change over time. Config describes rules and related settings. All three may be shared via a link, but they serve different purposes. Before importing, identify whether the content describes one server, a list, or a configuration, then choose the appropriate entry point. A particular prefix or the ability to open a link in a browser is not enough to determine which field to use.

Identify the Format; Don't Guess at Credentials

Common server sharing links may start with ss://, vmess://, vless://, or trojan://. The prefix helps identify the protocol, but the rest may not be shown as plain text: some formats use encoded data, others express an address and query parameters, and some include a display name. Let the app parse the original content, then check each field. Don't assemble a link from its appearance to make something that merely “looks about right.”

Encoding does not make text confidential. Importable content usually contains information needed to connect, and recipients may be able to read those parameters. Treat shared links as sensitive records, not ordinary bookmarks. A QR code is just another way to represent the same content; it does not change access permissions. Turning a link into a QR code does not reduce the impact of exposure.

Encoding, Line Breaks, and Display Names

Percent-encoding in links represents special characters; don't change it just to make the text easier to read. Characters such as plus signs, slashes, and equals signs can have different meanings in different formats. Spaces or line breaks inserted by a messaging app may also prevent the content from being parsed correctly. If fields are missing after import, first check that the original text is complete at both ends and hasn't picked up punctuation. Don't start by changing the server password.

Some formats use the part after # to store a display name, but this depends on the format. A name that looks like a region does not verify the server's location or determine connection quality. Changing the name alone usually won't change the connection destination, but editing sharing text may accidentally alter other parameters. For routine organization, change the note in the app; refer to the original details when changing connection parameters.

Rule Files Cannot Replace Server Details

Rules in Config determine how traffic is handled; they don't make incorrect server parameters work. The example below shows common rule lines in a Shadowrocket configuration to illustrate matching order and policy behavior. It is not a complete file to replace your own configuration. Before use, confirm that the required policies are available in your current Config and that DNS, server details, and other settings match your needs.

[Rule]
DOMAIN-SUFFIX,example.com,PROXY
GEOIP,CN,DIRECT
FINAL,PROXY

The first rule matches a domain suffix, the second matches a condition based on the destination IP, and the last handles traffic that matched none of the earlier rules. Rules are checked in order. The last line alone does not mean all requests use the selected server. To check whether rules are taking effect, select Config under Global Routing and review the configuration currently loaded. If Proxy or Direct is selected, you can't assume the same rule path applies.

If only some destinations behave unexpectedly after a successful server import, check routing rules instead of repeatedly importing the same sharing link. Switching Config won't fix an authentication error either. If the interface terms are unclear, see Home, Config, Proxy, and Direct Explained. Separating input format, server connectivity, and routing policy into three layers can prevent a lot of unproductive trial and error.

05 / Check Before and After Updating

Subscription Update Settings and Troubleshooting

Updating a subscription requests its list again and syncs the entries. It does not update the Shadowrocket app or extend the term of an existing service. App updates are managed through the App Store; subscription updates depend on the saved URL and its response. For a reliable update routine, first confirm that a manual update works, then consider automation. Avoid repeatedly triggering requests before you have verified the link.

Use a Manual Update to Check Status First

Find the subscription to update on Home and use its update action. Before you begin, note the group name, currently selected server, and any local notes you want to keep. After the update, check whether the entries changed as expected. The interface may vary, so use the action associated with the subscription rather than relying on a swipe direction or icon position. If you have several subscriptions, update one first and check the result before moving on to the others.

A completed update does not guarantee that the current selection is still valid. The list may replace an entry with another that has the same name but different parameters, or remove the selected server. Check the selection again after updating and run a connection test. If many entries have changed, compare the original records with the current response before assuming something is wrong; server maintenance or list changes can produce expected differences.

Enable Automatic Updates Only When You Can Verify Them

If the current interface offers automatic updates on launch or related settings, read the description before enabling them. Automatic updates depend on a trigger and the network available at that time; they don't mean the app syncs continuously. If the device has no network, the URL is temporarily unreachable, or the response can't be parsed, opening the app does not guarantee the list has refreshed. Judge by the update result and actual entries, not by whether the switch is on.

If you rely on a particular entry, schedule updates when you can check the result immediately, rather than making large changes just before you need a connection. A subscription that has tested successfully can be updated at a reasonable interval. If updates keep failing, find the cause instead of treating repeated retries as a fix. Automatic updates also do not replace backups: unwanted changes can sync locally too.

Check the Request, Response, and Parsing in Order

First, confirm the device can access the network; test under different network conditions if needed. Next, check that the URL is complete, has not changed, and still has valid credentials. Finally, check whether the response uses a subscription format the client supports. An account sign-in page, access notice, or error message is not a server list—even if the request received a response. Don't keep importing this kind of content into the address field in Add Server.

The route used to access a subscription URL may differ from the route used to connect to a server. So a working server does not prove that an update request will succeed. If you suspect a routing issue, check the current Global Routing mode and network conditions, then test one variable at a time instead of clearing the configuration. Keeping locally available entries can preserve the current setup while you troubleshoot. Rebuild the subscription only if you've confirmed the data is damaged and have a backup.

For more detailed steps, see Manual and Automatic Subscription Updates and Troubleshooting. When documenting an issue, include only the group name, approximate time, network type, and symptoms—never the real URL. This is enough to distinguish a temporary network issue from a persistent format problem and to compare results during the next update.

06 / Source Matters More Than Quantity

Organizing and Naming Multiple Subscriptions; Removing Duplicates

When managing multiple existing subscriptions, the goal isn't to pile every server into one long list. You should always know where each entry came from, how it is maintained, and whether it can be restored. Keep subscription groups distinct from manually added entries, use notes to describe their purpose, and check the selection state to avoid mistakes. Back up first, then organize one group at a time and make sure the current connection still works before continuing.

Use Two Levels of Names; Never Put Credentials in Notes

Use subscription names to distinguish lists and server names to distinguish entries within a list. A subscription name can describe its purpose, such as “Daily use” or “Backup test.” Keep enough of each server's original identifying information to recognize it after an update. Don't use notes to store the full subscription URL, password, or identity fields. Notes often appear on Home, in screenshots, and in sharing previews, so they are not suitable for sensitive information.

If you use the same subscription on multiple devices, consistent group names can help, but they don't mean the devices are synced. Each device may have a list from a different date, and its selected server and local notes may also differ. If the contents don't match, compare the subscription URL and update results first. Don't overwrite the current device by copying all settings from another one.

Entries with the Same Name Aren't Necessarily Duplicates

Compare connection parameters when removing duplicates; don't compare names alone. Entries with the same name may use different hosts, ports, or transport settings, while different names may describe identical parameters. Check at least Type, Address, Port, and any required transport settings before deciding that entries are duplicates. Credentials are part of a server's identity too, but compare them in private. Don't create a public spreadsheet of unmasked credentials just to organize entries.

If importing the same subscription twice created duplicate groups, keep the one that updates correctly and remove the confirmed duplicate. Similar servers from different subscriptions should not be merged hastily: they may have different update sources and maintenance status. Preserve the source information so you can later explain why an entry changed its name, stopped working, or disappeared. Clean up one group at a time rather than deleting every entry with a matching name.

Distinguish Display Order from the Current Selection

Sorting makes entries easier to find; it doesn't necessarily change the server currently selected for the connection. After moving an entry to the top, confirm that it is actually selected. Likewise, sorting by test results does not mean the app automatically switches to the first entry. When you're done organizing, check the selection indicator and test the connection. If several groups contain similarly named entries, open the intended group first to avoid selecting an older record.

If the current interface supports custom ordering, put frequently used groups where they're easy to find while keeping the original records available for reference. Avoid renaming every subscription entry just for a tidier list; an update may recreate them. For local notes you need to keep long term, use a private management record to note the purpose, subscription, and fields to check rather than relying on notes surviving every update.

Keep Test Entries Separate from Daily-Use Entries

Clearly label manually created copies made for troubleshooting. When you're done, decide whether to delete or keep them so you don't forget which entries are still maintained by a subscription. A separate copy will not inherit later parameter changes from the original subscription. Even if it has the same name, it can become outdated over time. Separating everyday use from temporary tests helps avoid selecting an old copy after the subscription has been updated.

After organizing, check that each group can still update, commonly used servers can still be selected, and test entries have been dealt with. For a more detailed checklist, see Organizing Multiple Subscriptions, Sorting, and Removing Duplicate Servers. For specific issues such as missing or duplicate entries, see Troubleshooting.

07 / A Number Tells Only Part of the Story

Connectivity Test, Latency, and Sorting

Connectivity Test shows how a server responds under the current test conditions; it cannot represent the whole user experience on its own. Lower latency usually means a particular test completed faster, but it does not directly indicate throughput, long-term connection stability, or access to every destination. First compare existing servers under consistent test conditions, then verify with real tasks. Don't treat a single result as a lasting conclusion.

Keep the Network and Method Consistent Before Testing

Make sure the device is on a stable network, and avoid switching between Wi-Fi and cellular during a test. Check the current test settings and target, and use the same method throughout a round of comparisons. Different methods produce numbers with different meanings: some focus on establishing a connection, while others include an application-level response. Don't rank results from different methods together or substitute numbers from another device or time for current observations.

After running Connectivity Test on Home, first identify entries that clearly don't respond, then test the available candidates more than once. Several consistent results are more useful than one unusually low number. Other network activity on the device can affect results. Reduce interference first, then decide whether a difference is really caused by the server rather than competition for local bandwidth.

Consider Timeouts, Variability, and Real-World Access Separately

A timeout means the current test did not return a result in the expected time; it does not by itself prove that a server has permanently failed. Possible causes include a device network interruption, an unreachable test target, failed server authentication, or a problem somewhere along the route. Compare against a known-good connection on the local network, then check the server parameters and test settings. If every entry fails at once, look for a shared cause instead of changing each password.

If a few entries fail while the others work, check the address, port, and protocol parameters of the failed entries. If a server passes the test but an actual destination remains unreachable, check Global Routing, the current Config, and the destination itself. Repeating latency tests blindly is unlikely to locate the problem: the test target may differ from the one used for your task, and the traffic may follow different rules.

Check the Routing Mode Before Interpreting Results

Under Config, different destinations may match different policies. A web page opening successfully does not prove that the selected server handled the request. If you switch to Proxy to troubleshoot, note the original mode and restore it when you're done. Direct can help assess access over the local network, but that result does not replace testing the server itself. State which mode you used whenever you compare results.

Use Sorting to Narrow Options; Use Real Tasks to Confirm

After sorting by latency, choose a stable candidate and try a task you actually need to do, such as accessing a site you're authorized to use or completing a normal data transfer. Check the initial response, sustained transfer, and whether the connection drops and reconnects. Don't test lots of unrelated content at once; that makes it harder to distinguish the effects of the destination, device network, and server. Long-term stability requires ongoing observation during actual use.

Region names can help with organization, but they are no guarantee of quality. Geographic distance is just one factor; routing, congestion, server load, and destination location all affect performance. Keeping a small number of verified candidates is more useful than chasing the lowest number on the list. Results change over time, so sorting is not a permanent verdict. After network conditions change, compare again using the same method.

After testing, confirm the final selection and keep at least one other existing, verified option. Don't delete every other entry just to tidy the list. For the difference between latency figures and real-world performance, see Choosing by Latency, Region, and Protocol. For connection permissions or first-time authorization, return to the Getting Started steps rather than attributing every issue to latency.

08 / Verify Recovery Before Deleting

Deleting, Backing Up, and Verifying a Restore

Before deleting anything, identify what it is: an individual server, an entire subscription, Config, and the app itself are different data layers. Deleting one entry may affect only the local list; deleting a subscription may also affect the group of entries it manages. Read each confirmation prompt carefully. The safest order is to save the information needed for recovery, verify that the backup is readable, and only then delete. “I'll remember it later” is not a backup.

Prepare Recovery Materials for Each Data Layer

For a subscription, keep at least the complete original URL and a note about its purpose. For a manual server, keep all required parameters. For Config, keep the configuration content currently in use and any relevant notes. A subscription URL can retrieve the current list, but may not restore past names, ordering, or local edits. A configuration file may not include every manually added server entry, so saving only a rules file does not back up everything.

If the current interface offers an export or backup action, check what it includes before saving the result in a private location you control. Don't assume every export includes credentials, subscriptions, local selections, and app settings. When the export is complete, verify that the file was actually saved, can be opened again, and has a useful name. An inaccessible location or an empty file is not a valid backup.

Check Dependencies Before Deleting a Subscription

First, check whether the entry you're about to delete is being used for the current connection. Switch to another verified entry or end the connection. If Config refers to a particular policy or server by name, check that those references will remain valid after deletion. Removing an entry from the list does not mean the rules will automatically find a replacement. After deleting it, check the Home selection and connection again so you don't leave a configuration pointing to a name that no longer works.

If you only want to remove duplicates, delete the group you have confirmed is redundant instead of clearing other settings as well. A locally deleted entry in a subscription may reappear on the next update if it is still in the list. To reduce persistent clutter, first learn what organization tools the current interface provides instead of repeatedly deleting entries. Subscription maintenance and local list cleanup are separate tasks.

Restore Starting with the Smallest Scope

After changing devices or setting things up again, restore the app purchase through the App Store first, then restore your subscriptions and configuration. Purchase history and server data are separate; getting the app does not guarantee that your subscriptions, parameters, and notes will return. See Restoring Purchases on a New Device for eligibility and purchase details. Check the App Store listing for system requirements and purchase eligibility on iPhone and iPad.

When restoring personal data, start with one subscription or one manually added server. Check the parsed details and complete a connection test before adding Config and other groups. Overwriting everything at once makes it hard to tell whether a failure is due to outdated server details, broken configuration references, or a difference in device settings. After a successful restore, check notes, ordering, and the current selection; a file opening successfully is not enough to confirm the restore is complete.

Restrict Access to Backups and Review Them Regularly

Store files containing server passwords or subscription credentials somewhere private and controlled, not in public shared folders. Anyone who can read a backup may have access similar to someone with the original sharing link. When reporting a problem, share only the necessary structure and remove sensitive URL parameters, authentication fields, and QR codes. If a backup is exposed, deleting the file is only the first step: replace the affected credentials and create a secure, reliable backup.

Follow a consistent maintenance order: back up before updating; check before testing; confirm an alternative before deleting. Handle one issue at a time and keep a brief, private change log. This preserves a clear path to recovery and helps you identify what changed if a problem comes up later. For your first connection, see Getting Started. For follow-up steps based on the symptom, see Troubleshooting.