Official Manual · Server Management

Shadowrocket Subscription & Server Management

If you already have subscription details or server credentials, use this guide to import, update, test, and restore them. New to Shadowrocket? Start with the Quick Start Guide to add a server and connect, then return here to check fields or manage existing entries.

Shadowrocket is available through two options: the iPhone and iPad app costs $2.99 as a one-time purchase on the App Store; check the App Store listing for system requirements. The Mac (Apple silicon and Intel), Windows, Android, and Linux versions are free, with installers available from this site's download page at /dl/shadowrocket/. Menu locations may vary by device.

01 Subscription Import

Import an Existing Subscription with Subscribe

First, identify whether the data points to a list or a single server

A subscription URL fetches a list of server entries. A share link describes a single connection and usually cannot be refreshed as part of a subscription. Both may look like long strings, so length alone is not a reliable way to tell them apart. Check the instructions saved with the data: if it is intended to fetch a list periodically, use Subscribe. If it lists a server address, port, and protocol, follow the steps for entering fields manually with Add Server. Web pages, sign-in pages, and configuration file URLs may also use standard web links; seeing https:// does not mean the URL is a subscription.

In this example, https://example.com/sub?token=xxxx illustrates the URL structure only; it will not return a usable list. The path, query parameters, and letter case in a real URL may matter, so copy the entire URL and do not remove anything after the question mark. Copy it from the original text, avoiding surrounding quotation marks, list numbers, and line breaks. Treat URLs containing access credentials like passwords. When transferring data between devices, do not paste the full URL into public notes, support ticket titles, or online parsing tools.

After adding it, check the group and the current selection

From Home, open Add Server, choose Subscribe from the type selector, paste the subscription URL you already have, and save. If there is a notes field, use a short label that identifies its purpose; do not use the URL or account name. Return to the list and check that the entry appears, then expand it to inspect its server entries. Confirm success by checking the visible items: seeing only a group name means the subscription may have been saved, but does not confirm that the list was fetched and parsed.

If you have multiple subscriptions, import one at a time. Check its name, expected protocols, and a few representative entries before adding the next. This makes it easier to identify which import produced an unexpected entry. After importing, make sure the selected server belongs to the group you just checked. An expanded list does not mean a server is selected or that the active connection has switched to a new entry. To check the first connection, follow the tutorial's Global Routing settings; saving a subscription and connecting are separate steps.

Troubleshoot fetch failures and format errors separately

When a refresh fails, note which step produced the error. For a network request failure, check that the device is online, then verify the URL scheme, hostname, and original path. For an access error, check whether the URL you have is still valid. If the request completes but no entries appear, check whether the response contains a supported server list. Some URLs return a sign-in page, an error message, or text intended for people to read; receiving a response does not mean it can be imported. Never submit a URL containing credentials to an online checker just to inspect its response.

If only some entries appear, keep the current result and compare missing entries against the original data, checking their protocols and required fields. Do not repeatedly import the list to fill gaps. An incomplete entry does not mean the entire subscription is invalid; likewise, a successful test of one entry does not confirm the others work. If old entries remain after a refresh, first determine whether they are standalone entries or part of an older subscription group, then decide whether to remove them. Keeping the original group when errors occur makes it easier to compare before and after an update.

02 Manual Setup

Add Server: Manual Fields and Protocol Selection

Choose the protocol first, then enter the original values

Add a server manually when you have details for a single server, need to check each parameter, or want to keep a separate test entry. From Home, open Add Server, select the protocol specified in your source data, then enter the address, port, and required fields for that protocol. The form changes with the selected protocol. If the form does not have a field listed in your data, check the protocol selection rather than placing the value in a different field. You cannot identify a protocol from its port: two entries may use the same port but require entirely different connection parameters.

If the form has separate host and port fields, enter only the provided hostname or address in the host field and the corresponding number in the port field. Do not add a web scheme, path, or port to the host field. If the source gives separate address and domain fields, fill them according to their stated purpose, even if the values look the same. The host determines where to connect; a TLS server name or transport hostname may be used at a different stage. Do not replace all these values with the server address or disable certificate checks to see whether a field is correct.

Key fields for common protocols
ProtocolCheck firstCommon mix-ups
ShadowsocksServer address, port, encryption method, and passwordThe encryption method and password are separate fields
VMess / VLESSAddress, port, UUID, and the transport and security parameters specified in the source dataPutting the transport path in the address field, or using parameters from one protocol with another
TrojanAddress, port, password, and the corresponding TLS parametersTreating the TLS server name and connection address as the same field
HTTP / SOCKS5Address, port, and any authentication details explicitly provided in the source dataIncluding the address scheme as part of the hostname
WireGuardPrivateKey, peer PublicKey, Endpoint, AllowedIPsSwapping the tunnel address and the peer's connection address
Hysteria2Address, port, authentication details, and TLS settingsReusing a password or transport settings from another protocol

Check authentication, transport, and routing parameters separately

For Shadowsocks, the encryption method and password should come from the same original entry. If you change the address, check whether those values changed with it. VMess, VLESS, and Trojan data may specify a transport method as well as identity fields. Preserve the leading slash and original capitalization in any required path. Do not guess values for optional fields that were not provided. When copying from rich-text notes, watch for full-width punctuation and trailing spaces, and do not combine parameters from different environments.

For WireGuard, Endpoint is the peer's connection address and port, while AllowedIPs specifies which destination address ranges are routed through that peer. It is not a field for the server hostname, and you should not broaden a narrow network range just to test. Keep PrivateKey on the device intended to use it or in a protected backup; never send it as the peer's public key. For details on how keys, addresses, and MTU relate, see WireGuard Parameter Guide.

Save a separate entry and change one field at a time

When testing new parameters, give the entry a distinct note and keep the known-working original. After saving, reopen the entry to confirm the original protocol is still selected and each required value is in the correct field. Return to the list, select the entry, and test it. Change only one suspected parameter at a time and record the result. If you change the address, transport, and certificate settings all at once, you will not know which change mattered even if the problem goes away.

Note where the failure occurs. If the hostname cannot be resolved, check its text and the device's name resolution first. If the connection cannot be established, check the port, current network, and transport parameters. If a connection is established but the destination is inaccessible, check routing and destination name resolution. Do not use screenshots showing a full configuration with credentials. If a manually entered entry is only for comparison with a subscription entry, label it accordingly and follow the backup section after testing so it does not remain mixed in with subscription entries.

03 Importing Data

Scan QR Code and Import from the Clipboard

A QR code is only a container; its contents determine how it can be used

A QR code may contain a single server share link, a subscription URL, or plain text. Scanning only reads the contents; it does not guarantee they can be added as a server. Check your own records to identify what the QR code contains, then go to Scan QR Code from Home. If the code is on another trusted screen, keep its full border in view and avoid glare. If the QR code image is on this device, use image selection only if the current screen offers it; otherwise, import the original text you have.

The QR scanner may appear even when camera access is disabled, but it may not be able to read an image. Check that the system allows the app to use the camera, then try again. If the viewfinder works but does not recognize the code, adjust the focus and screen brightness, and make sure none of the code's edges are cropped. If the app reads the contents but reports an unsupported format, the issue is not focus or permission. Check the original data to determine whether it is a subscription URL, share link, or other text, then use the appropriate import method.

Keep only the text you need to import on the clipboard

Copy one complete item from your original record, then switch back to the client. If the current screen offers clipboard import, check that the clipboard contains the value you just copied and follow the prompt. If no prompt appears, use the method for that data type: enter a subscription URL in Subscribe, or open Add Server to enter individual fields. Copying does not automatically add anything. Another app may overwrite the clipboard, or it may still contain a URL copied earlier. Take extra care when handling multiple entries, copying between devices, or switching accounts.

When copying from a chat message or rich-text note, check whether line breaks are visual wrapping or actual newline characters in the copied text. Copy the complete item again from the original record; do not include its title, attachment preview, or other links. If the content contains encoded characters, do not remove percent signs or equals signs that look unnecessary, and prevent your input method from replacing plain punctuation. Handle entries one at a time, checking each item's group and type before copying the next.

Compare the list before and after importing; don't rely on a prompt alone

After importing, return to the list and look for the new entry. If you expected a subscription, confirm that its entry appears and, after a successful fetch, that the group's server entries are visible. If you expected a single server, check its protocol, visible note, and host against the original data rather than relying on a matching name. If nothing new is identifiable, check whether an identical item already exists, then determine whether the error occurred during reading, parsing, or saving. Repeated scans when you are unsure whether an item was saved may create more duplicates.

For troubleshooting, compare QR and text import using the same known data. If text import works but the image cannot be read, check image clarity and camera permissions first. If both methods read the same text but neither can add it, check the format and supported protocol rather than switching scanner tools. If the two methods produce different text from the same item, compare it with the original record you control; do not rely on a note or caption beside the QR code to identify its actual contents.

05 Refreshing Lists

Subscription Update Strategy and Change Checks

Keep subscription updates separate from app updates

Refreshing a subscription requests the list again from its existing URL; entries in the group may be added, removed, or changed. Updating Shadowrocket replaces the app itself. These are separate processes. If one subscription is out of date, refresh that group instead of reinstalling the app because the list has not changed. If you want to check for an app update, refreshing a subscription repeatedly will not help. For app downloads and common issues, see the Download page. There is no need to change app update settings in the server editor.

Before refreshing manually, note the selected entry and its group, the network used the last time it worked, and the visible notes of a few dependent entries. There is no need to record passwords or paste a subscription URL into your notes. Then refresh only the target subscription. Wait for the request to finish before checking the group; do not also switch networks, change the URL, or refresh several groups at once. Your notes should help answer two questions: how the fetched list differs from the previous one, and whether a connection issue began after the active entry changed.

Choose a refresh schedule that suits the maintenance task

Manual refresh is useful when importing for the first time, replacing a URL, or troubleshooting instability. Handle one group at a time and check which one is being refreshed and its status when the request completes. If the current screen offers automatic updates, first confirm that the group can be fetched with a manual refresh, then choose a schedule based on how often its contents change. After validating a new device, do not enable automatic updates for every group at once when you cannot monitor the results. If an issue occurs, it will be harder to tell which group changed first.

Refresh frequency does not indicate connection quality. When the list is usually stable, focus on finding useful changes rather than shortening the interval between requests. For configurations that depend on specific entries, check after refreshing that the entries are still present and that the group name and selection have not changed. Automatic refresh may not complete at the expected time if the network changes in the background or the device limits background activity. If you need a recently updated entry, check the list manually; do not treat the scheduled interval in settings as the time of the last successful refresh.

Distinguish unchanged content, failed requests, and invalid selections

A refresh may return the same content; new entries are not expected every time. If the interface reports an error while the old list remains visible, those saved entries do not prove the refresh succeeded. For an access error, check the status of the original URL. For a network request failure, check the current connection and name resolution. For an empty result or format issue, check that the URL points to the right type of data. Do not clear the old group to test an update; doing so removes both a fallback and the sample needed for comparison.

If the previously selected entry has been removed, first check whether the subscription provides a clear replacement, then review the client's current selection and configuration references. Similar names do not prove that two entries use the same connection. Before selecting another, compare its protocol, host, and purpose. If the server list refreshes and the old entry is still there but a web page will not open, check routing and destination resolution rather than repeatedly refreshing the subscription. For more on this issue, see Troubleshooting DNS Resolution Failures.

06 Groups and References

Organize Multiple Subscriptions and Rule References

Name groups by their purpose, not by temporary sort order

When organizing multiple subscriptions, first clarify which group each entry belongs to rather than ranking the entire list. Give each subscription a short, stable note that identifies its purpose, such as daily use, test comparison, or migration review. Do not include full URLs, account names, or temporary test results in notes. Treat entries in different groups as belonging to separate sources even if they look identical: each group may refresh independently, and matching names do not guarantee matching connection parameters. Give manual entries distinct notes so they are not mistaken for new subscription entries after a refresh.

When organizing entries, distinguish subscription notes, which help locate a group in the list; server notes, which label individual entries; and policy names in the configuration, which are used by rules. They may look alike but are not interchangeable. Before changing a note in the list, check whether the current Config references the old name, especially in policy groups you edited yourself. Change one group or type of name at a time, then verify it in the connection and configuration screens. Do not combine renaming with bulk deletion.

Use rule snippets to check how traffic is routed

The server list contains available connections; rules determine which policy handles destination traffic. The snippet below illustrates rule order for reading or testing in a copy of your configuration. Do not use it to overwrite your entire existing configuration. The order of the first three lines matters: match domain suffixes first, then geographic IP conditions, then handle traffic that has not matched earlier rules. In the example, PROXY is a rule's policy target, not a subscription group named “Proxy”; traffic will not use it just because its group appears at the top of the list.

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

In this order, requests matching the example.com suffix use PROXY first. Requests that did not match the previous rule and meet the GEOIP,CN condition use DIRECT. Remaining requests fall through to FINAL. To check the rules, select Config under Global Routing, then observe a recognizable destination. Switching to Proxy or Direct for comparison only changes routing for the current test; it does not show how these rules match under Config.

Keep the old group during migration; remove duplicates last

When moving everyday entries to another subscription, keep both groups available and find the corresponding entry in the new group first. Check the configuration's default route, specific policies, and currently selected server, then verify each before switching. If you need an entry with its original parameters for troubleshooting, save it as a separate, clearly labeled entry rather than editing a subscription-generated entry and expecting refreshes to preserve it. During follow-up checks, focus on what the next refresh returns, not just what the list currently displays.

To verify the changes, test two paths: a destination you use regularly and another that should follow a different policy. This can reveal cases where the server works but traffic goes through the wrong group. If a problem starts right after switching, restore the previous selection or a copy of the configuration, then repeat only the last change. Use the same order when cleaning up: check references and selections first, remove standalone test entries next, and delete subscription groups only when nothing depends on them. Reordering entries in the list alone does not replace these checks.

07 Testing and Sorting

Connectivity Test, Latency, and Sorting

Set the scope of the test before comparing results

Connectivity Test checks whether an entry is reachable under the current network and test conditions. Results depend on the device's network, test target, connection method, and load at the time. They are not download speeds and cannot show that every website will produce the same result. To compare entries, use the same device, network, and test method. Do not switch from Wi-Fi to cellular during the test, or treat latency readings as a stable ranking while multiple entries are carrying heavy traffic.

Run Connectivity Test from the server list. Start with one group or a small sample of entries used for the same purpose, then expand after the results are complete. The first request may be affected by a temporary resolution, handshake, or network issue; wait a while before retesting if needed. When two readings are close, compare whether both entries remain usable over repeated tests. Prioritize ruling out intermittent entries rather than changing your default based on a small difference in one reading. If you only have a single result, treat it as an observation from that moment, not a long-term conclusion.

Distinguish timeouts, inconsistent results, and unavailable services

If only one entry times out, compare its host, port, and protocol with working entries in the same group. If an entire group or several groups time out, check the device's network and whether the test target is reachable before changing servers. If the results differ clearly after switching networks, record them separately rather than mixing them into one ranking. Do not delete failed entries before retesting; keep them as samples for comparison.

If latency results are available but a web page will not load, first check whether the request actually used the server you tested. Check the selected entry and Global Routing, then review the rules and resolution results. The test target may differ from the destination used by your app, so a normal result does not mean the service's domain resolves, and an unavailable service does not necessarily mean the server is offline. For related checks, see the tutorial's Data and troubleshooting steps. Compare changes only within a test setup you control.

Use sorting to filter candidates, not as a switch

If the current list offers latency sorting, apply it after the test run so entries with similar results are easier to compare. A timeout and an untested entry are different: the first has an incomplete test result, while the second has no result for this run. Focus on candidates that have been tested, can be retested, and suit their intended use. Sorting changes only the display order, not the selected entry. If the configuration has its own policy groups, check separately which entry each one references.

A maintenance record can be limited to the test network, entry note, test method, and whether the result worked. Include the group in the note to distinguish entries with similar names. Verify candidates against actual destinations before changing the default route, and note the current selection so you can restore it if needed. If the issue affects only one domain, continue by checking its rules and resolution rather than sorting the entire list again. Latency data helps with the current choice; there is no need to make one result a permanent priority for every future connection.

08 Cleanup and Recovery

Delete Servers, Back Up, and Verify Recovery

Confirm whether you are deleting an entry, subscription, or configuration

Before cleanup, identify what you are acting on. Deleting a manually added entry removes that server data locally. Removing a subscription may also remove the list entries it generated. Deleting a file from Config affects rules and policy settings. Check each type separately, and do not confuse changing the selected entry with deleting it. If the client lets you remove an entry from a subscription group locally but the original subscription still returns it, the entry may reappear on the next refresh. That does not mean the deletion failed; the list has been regenerated from the subscription.

Before cleanup, identify the currently used server and its group, then check the active configuration for other dependencies. If you plan to delete an entry in use, switch to a verified alternative first, test a commonly used destination, and make sure the original entry is backed up. Open the delete action from the management menu for the corresponding list item and check the scope shown in the confirmation prompt. If you only want to stop using a group, you do not need to delete it immediately. Keeping it for an observation period makes it easier to catch missed rule references or backup uses.

Back up each type of data separately

A backup should distinguish at least three things: subscription details that let you fetch a list again, standalone server entries that cannot be restored by refreshing, and the configuration file currently in use. A configuration file may contain rules and policy definitions, but exporting one file does not guarantee that it includes all servers, subscription URLs, or credentials. Likewise, saving one server in a share link does not save the Global Routing selection or configuration file. Check what the export actually includes and note in your own records what can be restored.

Store backups that need protection somewhere you control with access restricted. Record which device a backup belongs to, which groups it includes, and which configuration it contains. Do not put passwords, subscription query values, or keys in filenames. After exporting, make sure the file is readable and is not left in a public sync folder. A complete backup record should also identify anything that must be set up manually, such as settings or default selections not included in the export. This helps avoid mistaking options that have not yet been configured for a failed restore when moving to a new device.

Restore in stages and verify that the next refresh still works

Start by importing one identifiable subscription or a known standalone entry and confirm it appears in the expected place. Then restore the configuration file and check that its server or policy references match entries in the current list. Restore the routing selection afterward. Verify in two steps: first check basic connectivity, then use the original Config mode to confirm that destination traffic is handled as expected. Seeing “added” in the interface does not prove that the configuration, server, and active rules work together.

Finally, manually refresh one migrated subscription to confirm the backup restores not only old entries but also the means to maintain them. If the refresh fails but the old list remains visible, keep the current state and check the credentials and response format in the subscription section. If you discover after changing devices that the app itself is missing, reinstall the app before restoring its data. On iPhone or iPad, see how to redownload from your purchases. Restoring the app and restoring server data are separate tasks; neither step replaces the other.