Shadowrocket Subscription Setup: Subscribe, Add Server, QR Code & Clipboard

Add a subscription or server to Shadowrocket using Subscribe, Add Server, QR code scanning, or clipboard import. Learn how each method works and which formats it supports.

At a glance

This guide is for users who already have a subscription URL, server details, or QR code from a provider. Learn to tell refreshable subscriptions, individual server share links, and rule configuration files apart, then import using Subscribe, Add Server, QR scanning, or the clipboard. Finally, check the imported entries, test the connection, and keep track of the source for future updates. Instructions refer to the iPhone and iPad interface; on other platforms, check the equivalent features, as button locations may differ.

Before importing: identify what the link contains

Shadowrocket’s import options are separate from the source of your service. This guide assumes you already have a provider and subscription. We do not provide, sell, or recommend servers or subscriptions. Importing adds existing connection details to the client; it does not create a server account or extend your service’s validity.

First, check whether you received a subscription URL, a single-server share link, or a configuration file URL. Subscription URLs usually use HTTPS and may return multiple servers. A single-server share link typically begins with a protocol prefix. Configuration files may include DNS, rules, and policies. Although all three may look like a line of text, they do not necessarily belong in the same field.

4
Import methods: Subscribe, Add Server, QR code, and clipboard
3
Types to distinguish: subscription URLs, server share links, and configuration files
1–65535
Valid integer range for Port; use the value provided by your service provider

Subscribe: distinguish server subscriptions from Config subscriptions

If you’re looking for Subscribe on the Config page, first confirm what the subscription is for. Config manages configuration files, and its Subscribe option is for configuration subscriptions. Don’t load every server subscription URL as a rule configuration. If your provider specifically supplied a server subscription, the usual path is Home → “+” in the top-right corner → Add Server → Type → Subscribe. Both options may fetch a remote URL, but they save different content and have different effects.

A server subscription keeps its remote source, so refreshing it can retrieve the provider’s updated server list. A manually added server does not automatically become part of a subscription. Keep your current working entries before importing for the first time. Don’t clear Home just to troubleshoot one failed import, and don’t overwrite existing rules with a remote configuration unless you understand its contents.

  1. Confirm the content type

    Check the purpose of the link in the provider’s original instructions. Use Home for a URL identified as a server subscription. Handle a complete configuration file from Config using the configuration subscription option.

  2. Select Subscribe

    Go to Home → “+” → Add Server → Type → Subscribe. Switch the type to Subscribe before entering the URL, so you don’t paste the entire URL into the Address field for a regular server.

  3. Paste the full URL

    Paste the original subscription URL into the URL field, including any query parameters after the question mark. Give the entry a recognizable name. Check that there are no spaces or line breaks at the beginning or end.

  4. Save and check

    After saving, return to Home and wait for the fetch to finish. Check whether servers appear under the subscription. To fetch again, update that subscription instead of adding the same URL repeatedly.

Add Server manually: check each protocol field

If you have a server address, port, and credentials but no usable share link, go to Home → “+” → Add Server. Choose the correct protocol under Type, then fill in the fields. Shadowsocks, VMess, VLESS, Trojan, Hysteria2, and WireGuard use different authentication and transport parameters; don’t try to fit one protocol’s details into another protocol’s fields.

For example, enter the port assigned by your provider instead of changing it to 443 just because TLS is enabled. The server Address and TLS Server Name may also differ. For a WebSocket connection, keep the leading slash in Path. Host, Path, and TLS-related names each serve a different purpose; don’t replace them all with the server IP. If any details are missing, check with your existing provider rather than guessing.

Connection and authentication

Type
Choose the protocol specified by your provider, such as Shadowsocks or VLESS.
Address
Enter the server’s domain name or IP address, without a webpage path.
Port
Enter the assigned integer port. 443 is one possible value, not a universal answer.
Authentication fields
Enter the actual fields required by the protocol, such as Password or UUID. Values are case-sensitive.

Field names and required values vary by Type. Saving successfully does not mean authentication has been verified.

Transport and TLS

Transport method
Match the server configuration; the protocol name alone isn’t enough.
Host
Enter the request hostname provided by your service provider only when the selected transport requires it.
Path
For WebSocket, preserve the original path, including its leading slash.
Server Name
Use the value specified by the TLS configuration; don’t assume it is the same as the connection IP.

Don’t disable certificate verification instead of checking the domain, certificate, and system time.

After saving, check the entry details before testing the connection. Manually added entries generally need to be maintained by you: if your provider changes the port, password, or transport settings, restarting the app won’t update the old values. Keep a private backup of your details, and don’t put passwords in public notes.

QR codes: the encoded content can vary

A QR code carries text; it isn’t a protocol. It may contain a single-server share link, a subscription URL, or simply a webpage from your provider. Open the scanner from Home and grant camera access if prompted. Position the entire QR code within the scan area, then check the recognized content instead of connecting as soon as the scan succeeds.

Choose how to scan based on where the QR code is

QR code on another screen
  • Open your existing QR code on a computer or another device.
  • Open the scanner from Home and make sure the entire code, including its edges, is visible.
  • After scanning, check the protocol, server, and port before saving.
QR code on this device
  • If the scanner offers a photo library option, select a clear original image saved on your device.
  • If there’s no option to read an image in the current screen, use the text link supplied by your provider instead.
  • Import the text using the clipboard; don’t paste an image into the URL field.

If the scan result is a regular webpage, return to your provider’s original site to confirm its purpose. Don’t treat an arbitrary webpage as a subscription.

If the code won’t scan, first check for glare, blur, obstruction, or cropping. Keep the blank border around the QR code intact. If scanning succeeds but import fails, check whether the encoded text uses a supported format; enlarging the image won’t restore missing authentication details. QR codes containing full credentials should be kept private, just like subscription URLs.

Clipboard import: copy the original text first

The clipboard is useful for text links on your current device. Copy the complete line from a trusted source, switch back to Shadowrocket, and use the clipboard import prompt or the relevant import action in the app. If iOS asks for paste permission, allow it for this operation as needed. If no prompt appears, there’s no need to keep restarting the app. Depending on the content, enter the URL manually in Subscribe or use the import option for a single-server link.

  1. Copy only the link itself: Don’t include instructions such as “Tap to import,” Chinese quotation marks, or Markdown brackets. The text displayed on a webpage may differ from the actual link destination.
  2. Keep query parameters: The token after ? in a subscription URL is often used for authentication. Don’t keep only the domain and path, and don’t truncate parameters after &.
  3. Watch for escaped text: If the copied text contains the literal string &, you may have copied webpage source text. Copy the original link again rather than blindly replacing text throughout the URL.
  4. Check each imported entry: Text containing multiple server links may create multiple entries. Check the count and protocol before deciding what to keep, and avoid importing the same set twice.

If you see “Unable to recognize,” check the beginning and end of the text in a trusted text editor on your device. Don’t upload it to an online decoder. If the share link is encoded, you don’t need to decode it yourself and paste it into a regular server field; the client should receive the complete original share link in a supported format.

After importing: test the connection and keep track of the source

A completed import, a latency response, and a working webpage are three different checks. A completed import only means the details were parsed and saved. A test result reflects reachability using that specific test method. Actual access also depends on authentication, DNS, TLS, routing rules, and the destination site’s status. Select a specific entry on Home before testing the connection. Avoid changing servers, rules, and subscriptions all at once so you can compare results.

I pasted a subscription, but no servers appeared. Why?

Return to the subscription entry and check that the URL is complete. Then confirm that it returns a server subscription, not a login page or a full rule configuration. If authentication fails, check with your existing provider that the URL is valid. Don’t keep adding the same entry.

The QR code scanned successfully, but I still can’t connect. Why?

Open the new entry’s details and compare Type, Address, Port, authentication, and TLS settings with the original details. If they all match, check whether your current network allows the transport and whether the system time is set automatically.

A subscription fetch timed out. Which settings should I check first?

First check whether your current network can reach the subscription domain, then verify the URL and its validity period. If you need to fetch it through a proxy, you must already have a verified working connection. Enabling the relevant option alone won’t establish a connection if none is available.

I reimported the subscription and now have two identical server groups. What should I do?

Compare the subscription sources and names of both groups. Keep the correct source, confirm it can be refreshed, and then remove the duplicate. To update later, refresh the existing subscription instead of adding it again.

Download Shadowrocket