Official Manual · Server Management

Shadowrocket
Subscriptions & Server Management

Import, maintain, and restore existing subscriptions or server details. First distinguish subscriptions, servers, and Config files, then go to the relevant chapter.

This manual is a reference for users who need to check settings after importing, maintain multiple subscriptions, or migrate to another device. For your first connection, start with the getting-started steps in the user guide. Once you have completed a connection, return here to manage updates, sorting, and backups. Get subscription links from your provider; this manual does not cover subscription sources.

Shadowrocket is available for iPhone, iPad, Mac (Apple silicon and Intel), Windows, Android, and Linux. The iPhone and iPad app is a one-time $2.99 purchase on the App Store; the Mac, Windows, Android, and Linux versions are free. See the downloads page for all platforms for details. Interface labels remain in English. Menu locations may vary by device, so follow the options available in your current interface.

01 · Subscribe: Add and identify a subscription

Identify the type of content first

A subscription is an endpoint you can request again to retrieve a server list; it is not a single server in that list. A single share link usually describes one connection, while a Config file may also contain rules, DNS, and policy settings. Before importing, check the provider's description of the content; link length alone does not identify its type. Even if a Config file URL is reachable, entering it in a server subscription field does not mean the client can parse it as a server list.

Get subscription links from your provider. When copying, preserve the complete URL, including its path, query parameters, and capitalization. Make sure no characters are missing from the end. Messaging apps may wrap long links visually; those line breaks may not be part of the URL. If the copied text includes explanatory text, quotation marks, or extra spaces, copy it again from the original instead of trying to repair it by hand.

Use Subscribe to create a list you can maintain

In Home, open Add Server, select Subscribe under Type if that option is available, then enter the subscription URL and a recognizable label. If your interface has a separate Subscribe entry, you can go there directly to do the same. Before saving, confirm the content type: enter the subscription URL, not a server domain copied from it.

Use a label that identifies the source and purpose, such as “Personal subscription · Daily devices.” Don't put the full URL or credentials in a visible name. After saving, update the subscription and check whether server entries appear. Seeing a subscription record means the source may have been saved, but you still need to confirm that the list was retrieved. Saving and fetching are separate steps.

Check the import at three levels

First, check the request: can the client reach the URL, or is there a network error or expired authorization? Second, check parsing: is the returned content a server list supported by this entry type? Third, check the connection: do the parsed servers have complete settings, and can they connect? These are separate checks. A successful subscription update does not mean every server in the list works.

After importing, check whether the number of entries looks right, then spot-check the Type, address, and port of one or two servers. Some entry names may be descriptive and not used for the connection; the name cannot substitute for the actual fields. If the response is a webpage, login prompt, or error message, check subscription access and the URL rather than repeatedly changing server passwords.

ItemWhat it containsHow to maintain it
SubscribeURL for retrieving a server listKeep the source and update the list as needed
Server entryProtocol, address, port, and authentication settingsSelect, test, or check individual fields
ConfigSettings such as rules, DNS, and policiesManage separately and confirm which file is active

What to keep if the first update fails

If the update fails, keep the original subscription record and the complete error message. Don't delete and recreate it right away. Check that the device can access the internet, then verify whether the URL has expired or needs to be regenerated. If other websites also fail to load, troubleshoot the basic network first. If only the subscription request fails, focus on the URL and access requirements. Keep existing entries while troubleshooting so you don't lose useful clues.

If the same URL already works on another device, compare the entry type, URL completeness, and retrieval time—not the displayed name. A list cached on an older device does not prove that the current URL is still valid. When contacting your provider, describe the request stage and error. Don't include the full subscription URL in a public screenshot; share any required fields through an appropriate private channel.

02 · Add Server: Enter server settings field by field

Choose Type before entering shared fields

Add Server creates a server entry manually. Prepare the complete settings first, choose Type, then enter the address, port, and authentication details. The protocol determines which fields appear, so don't fill everything in and then switch Type at random. If your provider supplied a complete share link, import it instead to avoid losing transport or TLS settings while transcribing it manually.

Enter the server domain or IP in the address field, without the full path from a browser address bar. Enter the port separately, and make sure it isn't the port of a subscription webpage. The label is for identification only and isn't used for authentication. Before saving, check for spaces in numbers, punctuation after the domain, and line breaks introduced during copying. Watch for full-width punctuation inserted by an input method.

Authentication fields are not interchangeable just because their labels look similar

Shadowsocks typically requires an address, port, encryption method, and password. The encryption method must match the server; a correct password can't compensate for the wrong method. VMess and VLESS commonly use a UUID as the identity field; don't enter an account login password there. For Trojan, follow the server instructions for its authentication details. A password field in one protocol does not mean you can reuse the complete settings from another.

HTTP and SOCKS5 may use a username and password for authentication, depending on the server configuration. WireGuard uses keys, addresses, and peer settings; it doesn't work like a standard username and password. Hysteria2 also depends on UDP transport conditions. Check fields against the selected protocol instead of looking for values that work across every Type.

Setting categoryTypical fieldsWhat to check
Connection targetAddress, portWhere the server is actually listening
AuthenticationPassword, UUID, username, or keyThe field type and value both match
Transport settingsTransport type, Host, pathMatches the server requirements
TLSServer name, certificate validation, ALPNName and validation requirements match

Distinguish the server address, Host, and TLS name

The server address determines where the connection goes. Host may be part of a particular transport's request, while the TLS server name identifies the name used during the handshake. These values may be the same, but they don't have to be. Don't use one domain to overwrite every related field. A path is not the path in the subscription URL; enter the transport path supplied by the server, preserving the leading slash, capitalization, and any required query string.

If certificate validation fails, first check the device's time, the TLS server name, and the server certificate status. Disabling validation is not a general-purpose fix. Set ALPN and similar options only when explicitly required. Don't add parameters that weren't provided just based on guesswork; an apparently reasonable option can change an otherwise correct handshake.

After saving, perform one targeted check

After saving the entry, return to the list and confirm it is still the expected manual entry or source, then select it for testing. If you haven't confirmed the address, port, and authentication details, don't change DNS, rules, and transport settings at the same time. Change one setting at a time when you have a reason to do so, and note what happens before and after. That way, if things improve, you can identify which change helped.

A manual entry is useful for saving clear, standalone connection details, but it won't automatically reflect later subscription changes. If the server changes its password, port, or certificate name, the old entry may remain in the list but stop working. If the settings came from a subscription, try updating that subscription first. If you need a local copy, label its purpose so you don't mistake a temporary copy for a source that stays up to date.

03 · QR Code & Clipboard: Check the content before importing

A QR code is only a way to carry content

Scan QR Code reads the text in a QR code; the code itself does not indicate a specific protocol. It may contain a server share link, a subscription URL, or plain explanatory text. After scanning, review the recognized content and the item that will be created before saving. Don't skip checking the address and protocol just because the QR code came from an old chat; an image may contain settings that have expired.

On devices with camera scanning, open Scan QR Code and grant camera access when prompted by the system. Make sure the camera can see the QR code's entire border, not just the center pattern. Glare, image compression, and screen moiré can make scanning less reliable. Adjusting the distance may help more than repeatedly opening the scanner, and you don't need to change any server settings first.

Protect the original content when scanning from an image

If the current interface lets you scan an image, select the original image. If not, display the QR code on another device you own and scan it with the camera. When cropping, remove only irrelevant space around the code; don't cut off its edges. QR codes often contain connection credentials, so treat saved, synced, and shared images as sensitive information.

If scanning succeeds but importing fails, the issue may be with parsing the content rather than reading the image. Changing the camera angle usually won't help at this point. Check whether the recognized text is in a format supported by the client. If the QR code points to an information page, first determine what that page is for; don't save its URL as server settings.

Check what you've copied before importing from the clipboard

After copying a server share link, return to Shadowrocket and use the clipboard import option available in the current interface. Allow the paste when prompted by the system. Copy from the protocol prefix through the end of the link, without explanatory text such as “Server address.” Some chat apps display linked text separately from the actual URL, so confirm that you copied the link itself.

If the copied text contains multiple links, first check whether the client recognizes them as separate entries, then decide whether to import them in a batch. Don't repeatedly paste a mix of explanatory text, blank lines, and links without checking it. If some entries import and others fail, keep the successful ones and check each failed item separately rather than importing the entire batch again.

Checking the imported entry matters more than which import method you used

Whether you used the camera, an image, or the clipboard, open the resulting entry and check its Type, address, port, and required transport settings. A displayed name only confirms that some visible information was parsed; it may be just a label from the end of the share link. Compare entries with non-default TLS or transport settings against the original details, field by field.

When importing duplicates, compare the actual connection settings rather than just the names. Two entries with the same name may use different ports, and the same address may use different protocols. Delete extras only after confirming they are exact duplicates. If one entry belongs to a subscription and the other was imported manually, their update behavior differs. Preserve the source information before deciding which one to maintain.

Handle permissions and privacy separately

If camera access is denied, check Shadowrocket's camera permission in the system app settings; you don't need to delete the server list. If a paste prompt is denied, copy the content again and repeat the import, then check whether the system asks again. System permission problems occur before content is read and are separate from whether a server password is correct.

After importing, don't leave a complete share link on a public clipboard or in a public note. Don't post QR codes in public discussion forums for help. If you need to show an error, keep the error text but hide identity parameters, passwords, and QR codes in the address. If credentials have been exposed, get replacement information from your provider; deleting a local image does not invalidate old credentials.

05 · Update Policies: Separate list updates from connection problems

An update changes the list provided by its source

A subscription update requests the subscription URL again and uses the response to maintain its server list. It does not reinstall the app or refresh Config. An update may add, remove, rename, or change server settings, so treat a subscription as a data set maintained by its source. Don't rely on local edits to its entries as a permanent way to save changes.

Before updating, note the source and identifying details of the entry you're using, and make a separate backup if needed. In particular, avoid updating every source, changing rules, and deleting old entries all at once while you need a stable connection. Complete one maintenance task, then check the result. This makes it easier to understand changes in state.

When to update manually and when to check automatic updates

You can update manually when adding a subscription for the first time, after your provider announces changes, or when an existing entry clearly stops working. Repeated requests in a short period usually won't fix an authorization issue and may only add unhelpful failure records. After a failed request, read the error and check the basic network first. Try again once the conditions have changed; that is more informative than clicking Update repeatedly.

If the current Subscribe or Settings interface offers automatic updates, set them to match how often you use the subscription and check the device's background activity settings. The system may limit background activity, so automatic updates don't replace a manual check before important use. Don't assume that refresh behavior seen on one device means all devices update on the same schedule.

Trace the request when an update fails

First check whether the domain resolves, then whether the URL is reachable, and finally whether the response can be parsed. If identity parameters have expired, the network may work normally while the response contains an error. A certificate or device-time issue may also stop the request before the list downloads. Changing the port on an individual server won't fix authentication for the subscription URL.

Also consider the network and routing state used to retrieve the subscription. If the current connection isn't working, it may affect the request. First check basic connectivity on a trusted network that works normally, then use the options available in the interface. Don't keep proxy or certificate settings from an unknown source just to make the URL temporarily reachable.

Check what changed after a successful update

Even if the update reports no errors, check whether the server list is empty, frequently used entries have been renamed, or the current selection has changed. An empty list may reflect changes at the source or an account issue; “request complete” alone does not prove the result is complete. Note what happened and when, check your provider's information, then decide whether to update again or replace the URL.

If an old entry disappears, don't blindly add its old settings back to the subscription group manually. First determine whether it was retired, renamed, or removed because of a list issue. If you need to keep a known entry temporarily, manage it as a clearly labeled manual copy and remember that it no longer follows the source automatically. This helps prevent local edits from being overwritten by the next update.

Distinguish server updates, rule updates, and app updates

Server updates change connection targets and authentication details. Config updates change rules and related settings. App updates update Shadowrocket itself. These operations can produce similar symptoms, but they affect different things. If a server connects but only certain domains take the wrong route, check the rules first. If several entries fail authentication, check the source settings rather than immediately reinstalling.

App updates for iPhone and iPad are managed through the App Store. For update details on other platforms, see the downloads page for all platforms. This manual doesn't recommend reinstalling as the first response to a list issue, since removing the app may also remove data needed for troubleshooting. For installation or first-launch issues, follow the installation instructions on the downloads page; don't conflate them with subscription problems.

06 · Organizing Multiple Subscriptions: Keep Sources and Maintenance Relationships Clear

Group by source before sorting by use case

The first goal in managing multiple subscriptions is knowing where each server came from, who updates it, and how to restore it if deleted. Keep the original source boundaries and use labels to distinguish everyday use, testing, and temporary copies. If the current interface offers grouping, collapsing, or filtering, use those features to reduce clutter. Otherwise, clear source labels can keep the list easy to review.

Don't copy every server into a manual entry with no source information. That may seem convenient at first, but later it becomes difficult to tell which passwords have changed or which entries are no longer maintained. Source information is part of maintenance, not just a decorative label. To keep using a source over time, maintain its subscription entry rather than relying on a batch of static copies from a one-time import.

Use labels that don't expose credentials

Labels can include a short source name, purpose, and necessary device identifier, but not passwords, subscription identity parameters, or full connection URLs. Long names may be truncated in the list, so put the most important source identifier first. Treat descriptions in server names with care: a name does not mean the client has verified that capability.

For a temporary manual copy, add a clear suffix such as “Manual check” or “Migration copy,” then remove it when you're done. Don't use claims like “fastest” or “permanent” in place of identifying information; they may not remain true. The same server can perform differently on different networks. Record test results separately instead of continually renaming the source entry.

When removing duplicates, compare settings and update relationships

The same name doesn't mean two entries are duplicates, and the same domain doesn't necessarily mean they are either. Before deciding, compare protocol, address, port, authentication, and transport settings, and check whether the entries belong to different subscriptions. Even if two sources return the same settings now, they may change independently later. Before deleting an entry, confirm whether you still need its ongoing update relationship.

A common case for deduplication is importing the same share link more than once by scanning or pasting it. Keep one verified entry, delete the extra copies, and check that the current connection isn't still using an entry you're about to remove. For similar entries within a subscription, preserve the source list as provided where possible, rather than repeating manual cleanup that won't persist after each update.

List order is not a routing policy

The displayed order helps you find entries; it doesn't determine Config rule order or prove that the first server carries all traffic. The actual route also depends on the selected entry, Global Routing, and policy references in the configuration. If you change both the sort order and the current selection while organizing the list, check them separately so a change in display position isn't mistaken for a change in routing.

Having multiple sources doesn't mean the client automatically combines their servers into a switching policy for you. If the configuration contains policy groups or explicit references, check their members and selected state. A new server appearing in the list doesn't mean the existing configuration will use it automatically. If you're unfamiliar with the rules, keep the current working configuration, organize the servers first, and change rules separately afterward.

Check the result through a full maintenance cycle

After organizing the list, don't just check that it looks tidy now. Run a planned update and confirm that source labels, manual copies, and frequently used selections are still recognizable. If an update overwrites local names, move information you need to keep into a separate maintenance record instead of relying on source-generated entry names. Store maintenance notes separately from credential files.

Then check at least one server from each source you're still using, including its settings and connection result. Back up and document sources you no longer use before deciding whether to remove them. Find out what an entry is for if its source is unclear; don't guess from the name. The aim is to reduce repeated maintenance, not make the list as short as possible or merge sources into an untraceable group.

When multiple people share a device, clarify who is responsible for updates and who can edit labels and configuration. Server data on the device may contain personal credentials; sharing a device doesn't mean those credentials should be exported freely. For a handoff, explain the scope of the changes and give recovery materials to someone authorized to manage the subscription. Ordinary usage notes should contain only a short source name and the outcome.

07 · Connectivity Test: Latency, Sorting, and Troubleshooting

A test result answers only the question it measures

Connectivity Test checks how an entry performs, but different test methods may verify different layers. Basic reachability, a protocol handshake, and loading a real webpage are not the same test. A reported time does not mean every app request has succeeded, and a failed test does not prove that the subscription is invalid. Check which test method is being used before interpreting the result.

Latency reflects the round-trip or request time under a particular test; it is not sustained transfer speed. A server that responds quickly may still be unstable on long connections or particular networks. Conversely, a slightly higher time may not affect your actual task. Compare using the same test method, similar network conditions, and a reasonable number of attempts. Don't treat one result as a long-term ranking.

Use a consistent testing process

Before testing, make sure the device's basic network is working, and avoid taking measurements while the system switches between Wi-Fi and mobile data. Test one server with complete, known settings first, then test other servers from the same source in a batch. If every batch result fails, check shared conditions before assuming every server is broken. Avoid changing rules or DNS repeatedly while testing.

Record the test method, network type, and specific behavior without putting full credentials in your notes. If an entry sometimes succeeds and sometimes times out, test again after a short interval and check for links to network changes, device sleep, or load. Repeated tests in quick succession may produce results that are hard to compare; more taps can't remove uncertainty in the network itself.

Check settings according to the stage where the test fails

If all requests fail, first check the basic network, domain resolution, and current routing. If only one entry fails, check its address and port. If the connection is established but authentication fails, focus on the password, UUID, or relevant identity field. For TLS errors, check the device time, server name, and certificate requirements. Narrowing the issue by stage is more useful than toggling every advanced option.

For protocols that use UDP, also consider whether the current network allows that traffic. If the same settings work on one network but consistently fail on another, note the difference rather than immediately replacing correct settings. Protocol transport requirements, server status, and device networking can all affect the result; a timeout alone doesn't identify the cause.

SymptomCheck firstDon't conclude yet
Subscription update failsURL, authorization status, request networkEvery server is invalid
One entry consistently times outAddress, port, protocol, and transportThe app must be reinstalled
Test passes but webpage failsGlobal Routing, rules, DNS, and destinationEvery setting is correct
Results differ after changing networksNetwork restrictions and transport conditionsThe entire configuration needs rewriting

Sorting helps you filter; it doesn't verify real-world access

If the current list can be sorted by test result, use it to find entries that need another look. Sorting doesn't prove that the top entry is best for long-term use. Don't delete every timed-out entry immediately; first check for a temporary network issue. The list and test results may change after a source update, so treat sorting as an organizational aid, not a permanent fact.

After selecting an entry, return to Home and check Global Routing, start the connection, then test it with your normal activity. Compare the system connection status with the actual result, and check the relevant connection log if needed. If the destination matches DIRECT, whether the server test passes may not affect that request. Check the route before evaluating the selected server.

Keep the smallest reproducible example

When contacting your provider, describe the protocol, failure stage, test method, and network environment; that's more useful than simply saying “it won't connect.” Hide server identity parameters in public reports, and check screenshots for QR codes and URLs in the list. A reproducible issue usually needs only one server entry and a clear set of steps, not an export of all subscription data.

For further troubleshooting, see What to check when a server times out. Common connection issues are covered on the FAQ page. If the issue is a system authorization prompt during your first connection, follow the guide to adding a VPN configuration first. Don't confuse incomplete permissions with a server problem.

08 · Deletion & Backups: Restore What You Need, Not Everything from Scratch

Identify the four types of data to keep

A backup should distinguish subscription entries, manual servers, Config files, and personal maintenance notes. A subscription entry helps retrieve a list; manual servers preserve standalone settings; Config preserves rules and related options; maintenance notes explain sources and purposes. Keeping only one type may not restore the original behavior. For example, a server link alone can't restore a rule order you customized.

Before starting, check which export or sharing options the current interface provides, then confirm what each one includes. Don't assume that one export button includes everything. For subscriptions, keep enough source information to identify the group after importing it again. Name backups by purpose, but don't expose passwords or full identity parameters in file names.

Store backups as credential files

Server links, QR codes, and exported files may contain passwords, UUIDs, keys, or subscription identity details. Encoding does not make them less sensitive. Store them somewhere you control access to, using protected storage when appropriate. Don't paste complete files into public support pages or put credentials in screenshot titles or shared file names just to make them easier to recognize.

If you use a device sync service to store files, check your account sign-in status, sharing scope, and access from other devices. A backup is not better just because it is copied more widely; it should be safely accessible when you need to restore it. Before handing an old device to someone else, confirm that the new device has restored successfully, then remove links, QR codes, exported files, and related clipboard history from the old device.

Deleting a server, subscription, or Config has different effects

Deleting a manual entry usually affects that connection record. Deleting a subscription entry may also affect its managed server list. Deleting Config affects rules and configuration selection. Before confirming, read the interface prompt and check exactly what will be removed. Don't delete an entire source just because one server fails a test, or delete a configuration to fix an authentication field.

A server entry deleted from a subscription may reappear after the next update if the source still returns it. To reduce clutter over time, use the organization features in the current interface where available, or keep source boundaries clear. If you're retiring a source completely, back it up and switch the current connection before deleting the entry. Then check whether any configuration still refers to it.

Restore items in dependency order

On a new device, first install and open Shadowrocket, then import subscriptions or manual servers, restore Config, and finally check Global Routing and the current selection. See the downloads page for all platforms for platform-specific access. Interfaces may be organized differently across devices, so compare items and fields during migration rather than relying on the old device's tap locations.

After reimporting a subscription, update it once to confirm the URL still works. Spot-check manual entries field by field. After restoring Config, don't assume it is active; check the selected file and confirm that its policy or server references exist. You may also need to grant system VPN configuration permission again. Importing data does not replace device-level connection authorization.

Test your backups with a restore check

After backing up, perform a small, non-destructive check: confirm the files can be read, exported items can be identified, and subscription URLs map to the right sources. If you have another device of your own, test restoring one server and one configuration first. If you don't, at least check what the files contain and where they're stored. A file's existence alone doesn't prove the backup is complete.

A successful restore means the list sources are recognizable, key settings match, Config is selected, Global Routing is as expected, and your actual activity works. Only then should you deal with old copies and duplicate entries. Don't clear the only working device before verifying the restore, and don't use app deletion to clean up a few duplicate records.

If you deleted data without a local backup, try retrieving subscription-managed items again through an existing subscription entry. For manually entered settings, retrieve them from your original records or provider. If credentials have been exposed or changed, restore with the new information instead of trying to recover old files. When finished, follow the connection checks in the user guide to complete the maintenance cycle.