Shadowrocket
Import a Subscription and Connect for the First Time

Prepare your details: subscriptions, servers, and Config

First identify what kind of details you have. A subscription link is usually used to import and update a group of servers. Details for a single server include its protocol type, address, port, and authentication fields. A Config file mainly controls behavior such as rules, DNS, and policies. These serve different purposes. Entering a configuration file address as a server subscription may cause an import failure or leave the server list empty.

Keep the original instructions from your provider somewhere you can refer to. A subscription link may contain account credentials, so copy it in full and do not share it in comments, screenshots, or group chats. When entering details manually, the protocol type must match the information provided; a server address and port alone are usually not enough. If details are missing, ask the original provider what the fields mean rather than guessing.

Also confirm that the device itself has a working internet connection. If the current Wi-Fi network requires browser authentication, complete it first. If ordinary web pages do not load even with Shadowrocket off, resolve the basic network issue first. This makes it easier to distinguish device network problems from server configuration problems. The steps below start by adding the first selectable entry in Home.

01 · Add Server: Add a server or import a subscription

Have a subscription link? Select Subscribe

Open Shadowrocket, go to Home at the bottom, then tap the plus sign in the upper-right corner to open Add Server. In the type selector, find Subscribe and paste the full subscription link into the URL field. If there is a notes field, enter a name you can recognize later to distinguish the source. A note is only for local identification and will not fix a problem with the link itself.

Before saving, check that the beginning or end of the link does not include spaces, line breaks, or explanatory text. In particular, do not copy only the shortened text displayed in a chat. When you are sure, tap the save button on the page, return to Home, and wait for the subscription content to load. A successful import is indicated by actual server entries in the list, not just a subscription name. You can leave the connection switch off for now.

If you see a subscription group but no servers, first use the update action for that subscription entry and check for an error. An expired link, incomplete authentication details, or a basic network that cannot reach the subscription address can all prevent its contents from loading. Do not add the same link repeatedly and create duplicate groups. Keep one copy and check the original URL and the provider's instructions.

Have details for one server? Enter them for its protocol

If you have parameters for a single server, open Add Server from the plus sign in Home as well. Choose the protocol specified in the details, such as Shadowsocks, VMess, VLESS, Trojan, or another matching protocol—not Subscribe. Enter the address, port, and authentication details as provided, then check additional fields such as TLS and transport settings one by one. Which fields are needed depends on the protocol and server configuration; do not omit them just because the interface lets you leave them blank.

If your provider supplied a QR code that the client can recognize, you can use Scan QR Code. The first scan may require permission to access the camera. After scanning, check the detected type and fields before saving. A QR code may also contain connection credentials, so do not show it to others. If scanning produces only an ordinary web address, check the original instructions to confirm its purpose instead of forcing it into a server entry.

After completing either import method, return to Home and confirm that the server you want to use is listed. This only means that the details have been saved; it does not confirm that the server is reachable. Next, select the default server and a routing mode for requests. These determine how traffic is handled after connecting.

02 · Global Routing: Select a server, then a mode

In the Home server list, tap the circle to the left of the target server to select it. Tapping the server name or its details may open the edit page without selecting it. Return to Home and check the circle again. If a subscription has multiple entries, select one to start with; do not switch servers while changing other settings.

Next, open Global Routing in Home. The three common modes are Config / Proxy / Direct. They affect which policies handle requests; they do not change the server account itself or make an invalid server entry usable again.

Config: Route traffic according to the current configuration

Config is suitable for everyday use when you need to route traffic by destination. After selecting it, go to the Config page and confirm which configuration is currently enabled. Check which requests it sends to PROXY and which it sends to DIRECT. Seeing a file on the Config page does not mean it is enabled; confirm its selected status. If you were given a matching configuration, read its purpose before deciding whether to import and enable it.

Rules are processed in matching order, and a specific destination may match another rule before it reaches FINAL. So when using Config, the fact that a website opens does not automatically mean it went through a proxy. You do not need to write a full set of rules when getting started; just identify the current configuration and understand roughly how it routes traffic. For more on editing configurations and protocol fields, see the protocol reference. Related options are covered in the settings guide.

Proxy and Direct: Distinguish between routes

Proxy is mainly for routing requests handled by the client through a proxy path, which helps you check whether the selected server works. It does not guarantee faster speeds, and an unavailable server will still prevent access. After testing, if you need to route destinations by rules, return to Config and verify access again.

Direct is mainly for direct connections and should not be used to prove that a server is working. Even if the connection switch stays on, being able to access a website in Direct may only show that the basic network is available. After switching modes, return to Home and confirm that the displayed value matches your selection, then proceed to connection authorization.

03 · Home: Turn on the connection and complete system authorization

Return to Home and make one final check: the circle selects the server you want to test, and Global Routing shows the mode you just chose. Then turn on the connection switch at the top. The first time you connect, iPhone / iPad may show a system prompt to add a VPN configuration. Confirm that Shadowrocket initiated the request, tap Allow, and complete device authentication as required by the system.

This authorization creates a network configuration on the device. It does not ask you to submit a subscription password, and you should not give your device passcode to anyone. After the system prompt closes, return to Shadowrocket and check whether the switch remains on and the connection is stable. Avoid tapping the switch repeatedly before you have handled the authorization prompt, or it may be unclear whether the action took effect.

If you previously denied authorization, follow the actual prompt the next time you turn on the switch. You can also search for VPN in system Settings and check whether a Shadowrocket configuration is present. If device management policies apply, adding a VPN configuration may not be permitted. Follow your device management requirements instead of repeatedly deleting other system configurations.

If another VPN configuration is connected, disconnect it first, then return to Shadowrocket and try again. This avoids repeated state changes caused by the system switching configurations. The switch turning off immediately after you turn it on, or the app showing that it is disconnected when you return, is different from a connection that stays active while web pages fail to load. These need different troubleshooting steps. Once the switch stays on, continue to Connectivity Test rather than stopping at the status icon.

04 · Connectivity Test: Verify the connection and access

Find Connectivity Test in Home, run it, and wait for it to finish. The test provides diagnostic clues about the current connection. If it fails or times out, note the selected server and Global Routing mode before moving on to troubleshooting. This guide does not assume a fixed latency or a successful result; actual performance depends on the device network, server, and current policy.

Then open a browser and visit a destination you actually need to use. Confirm that the page loads completely rather than showing only a cached title or old content. Refresh the page if necessary, then check whether images, subsequent requests, and the sign-in flow work. A successful test only shows that the test destination was reachable at that time. It cannot guarantee that every website or app uses the same route or replace verification of your actual use case.

To distinguish a server connection problem from a rules problem, note your current settings, test the same destination in Proxy, then switch back to Config and repeat the test. If the results differ, first check the rules, policies, and DNS for that destination in Config rather than immediately replacing all server details. Keep the basic network and test destination the same so the comparison is meaningful.

To check how a request was handled, review the available connection or request records. Find the entry for the destination and test time, then check the policy used. Traffic changes in Data can help confirm activity, but an increase in traffic alone does not prove that a specific destination used PROXY. Records may contain personal browsing information; remove subscription credentials, account details, and unnecessary destination records before asking for help.

The first connection is complete when the switch stays on, Connectivity Test returns a usable result, and the actual destination is accessible as expected. If you later change the server, Global Routing, or Config, repeat the same checks rather than assuming the previous result applies to the new configuration.

05 · Common failures: Change one variable at a time

The list is empty after import

Return to the subscription details and check that the type is Subscribe, the URL is complete, and the content loaded successfully after saving. Confirm that the device can access the internet while disconnected, then try updating the subscription. If the original link requires account authentication or has expired, check with the original provider. A subscription name and server entries are not the same thing; repeatedly turning the connection switch on will not fix an empty list.

The switch will not stay on

First check whether system authorization to add a VPN configuration is complete, then check the system VPN settings for another active connection. If the device is managed, confirm any applicable restrictions. Address system authorization and connection status first; do not start by changing DNS or replacing many rules, because requests may not yet be reaching the expected network processing flow.

The switch is on, but Connectivity Test fails

Return to Home and confirm that the circle still selects the expected server, then check the address, port, and authentication fields. For manually added entries, pay particular attention to whether the protocol type matches the TLS and transport parameters. If a subscription provides multiple entries, switch only the server and repeat the same test while leaving other settings unchanged. If there is only one entry, do not guess ports or passwords in an attempt to fix it.

You can also compare Wi-Fi and cellular networks, but keep the server and mode the same before and after switching. If only one network fails, first check whether it requires authentication or has local connection restrictions. Record what you changed in each comparison. Do not change the network, server, and configuration at the same time, or it will be difficult to tell what made a difference.

The test returns a result, but a specific website will not load

Check Global Routing first. If the website works in Proxy but not in Config, check whether it matched the expected rule and whether that rule's policy is available. Being able to open it in Direct does not prove that the server is working. Troubleshooting one destination should focus on that destination; do not attribute one website's failure to the entire client.

DNS can also cause a connection to be established while domain names remain inaccessible. Note your current DNS settings, then check how resolution works against the instructions for your current configuration. Do not add addresses from unknown sources. If request records indicate a domain resolution problem, address that first rather than repeatedly importing the same subscription. Protocol connections and domain resolution are separate steps and need to be verified separately.

It worked before, but stopped after a subscription update

A subscription update may change the server list. First check whether the selected circle still points to an existing, usable entry, then check whether the policies referenced in Config still have an available target. Updating server details does not update the entire configuration. If only one of these was updated, the other may still contain old settings. Check whether the original provider changed any fields before updating them.

If the issue persists, note the basic network type, selected protocol, Global Routing mode, test results, and each change you have already made. Then consult the protocol reference and field guide. To review the operation order, revisit the Add Server steps. Describing the specific step that failed is more useful when asking for help than simply saying “it doesn't work.”

Three checks to keep in mind

Before everyday use, confirm the server selected in Home, the current Global Routing mode, and the enabled configuration in Config. If access changes after updating a subscription or switching networks, repeat the tests in this guide's order. When you do not need a connection, turn off the switch in Home and confirm that the basic network is working.

You do not need to start by learning a large set of rules. First get familiar with the complete “import → select → connect → verify” flow. Then see the settings guide to learn about options such as On Demand, or consult the protocol reference to check what your server's fields mean. Keep the original connection details and record the current settings before making changes so you have a clear reference if you need to revert.