This article addresses common questions about “how to import nodes into sing-box”: once you have a subscription URL, a node sharing link, or a JSON file, which import option should you use, and what should you check—IP, DNS, or browser settings—if you can’t get online afterward? Menus vary between platforms and clients, so the steps below are organized by configuration source.
1. Check the client and node format first
sing-box is a proxy core, and clients built around it don’t necessarily offer the same features. First, check the app’s name and version on its “About” page, then see whether its configuration screen supports remote subscriptions, local files, or sharing links.
- Remote configuration URL: Usually fetches a configuration over HTTPS, but being able to open the URL doesn’t mean the format is compatible.
- JSON file: It should be a complete client configuration compatible with your current sing-box version, not just a node fragment.
- Sharing links such as vless:// and vmess://: These can be imported directly only if the client explicitly supports parsing them.
Don’t treat Clash YAML, node sharing links, and sing-box JSON as the same format. If your provider only offers a Clash subscription, ask whether they can provide a sing-box-compatible version. Simply changing the file extension won’t work.
2. Import nodes based on the configuration source
- Install a client from a trusted source that’s suitable for your system. After launching it for the first time, open the “Configuration” or “Profiles” page.
- If you have a remote configuration URL, select the option to add a remote configuration or import from a URL, enter a name, paste the URL, and save it. Option names vary by client; if this feature isn’t available, don’t try to follow these steps anyway.
- If you have a complete JSON file, select the option to import a local configuration and choose the file. If an error appears, note its details and check which version the configuration supports. Don’t delete fields at random.
- If you only have a single node sharing link, check whether the client offers an import-from-clipboard or QR code option. If not, ask the provider for a complete configuration or use a client that explicitly supports importing that protocol.
- Select the configuration you just imported, grant system VPN permission if needed, and start the connection. If the configuration provides a node selection screen, choose the node you want to use.
A successful import doesn’t mean the connection is working. First, try opening a regular webpage, then test the site you want to access. Whether you use this site’s free nodes or a configuration from another source, check the update time and format notes. Free resources may not always be available.
3. If it doesn’t work after import, troubleshoot in order
Start by checking the logs for configuration parsing errors, authentication failures, or connection timeouts. For parsing errors, check the format and version first. For authentication failures, verify the node details. For timeouts, check your local network, node status, and whether the subscription has expired. Temporarily disable other VPN or proxy tools to avoid routing conflicts.
Next, check how traffic is being routed: system proxy and VPN/TUN modes cover different types of traffic, and some apps may not follow the system proxy. If the exit IP you find hasn’t changed, that doesn’t necessarily mean the node is down; the site may be set to connect directly by the routing rules. Check the rules and logs, and test with other sites before drawing a conclusion.
If the client shows that you’re connected but you can’t open domain names, check the logs for DNS errors and follow your configuration provider’s instructions. Don’t change your system DNS, client DNS, and browser secure DNS settings all at once, or it’ll be harder to identify the cause.
4. Can browser settings affect test results?
Yes. Browser proxy extensions, secure DNS, cache, and site cookies can all affect how pages load. Try disabling proxy extensions and testing in a private window. Private browsing doesn’t automatically change your exit IP. Adjust only one setting at a time, and keep the change only if it helps. This makes it easier to distinguish between a node failure, a DNS issue, and differences caused by your browser environment. Subscription URLs may contain access credentials, so don’t share the full URL or configuration when troubleshooting.