Before you begin: clients, subscriptions, and baseline tests
Choose a client for your device, then pick the right package
For desktop, start with v2rayN; for Android, start with v2rayNG, which uses the Xray core. Consider v2flyNG as an alternative only if you have confirmed that your configuration requires the V2Fly core. The client provides the interface for importing profiles, switching settings, and viewing logs; the core establishes connections and handles routing. They are not the same thing. Seeing a node in the list only means the client has read the entry. Whether it can start or recognize a security option also depends on the core currently in use. Choose a package based on the architecture reported by your system—not the device model, processor brand, or what worked on another computer.
| Platform | Client | How to choose a package |
|---|---|---|
| Windows | v2rayN | x64; desktop edition listed first, classic WPF edition second |
| macOS | v2rayN | Choose arm64 for Apple Silicon or x64 for Intel |
| Linux | v2rayN | Choose deb or rpm first, then x64 or arm64 |
| Android | v2rayNG、v2flyNG | Choose arm64 or universal, based on the architectures supported by your system |
Know the difference between subscription URLs and individual share links
A subscription URL fetches a set of configurations periodically and belongs in a subscription group. An individual share link beginning with vmess://, vless://, or a similar scheme should be imported from the clipboard or scanned as a QR code. Saving a subscription URL does not mean the client has fetched its entries; update the relevant group after adding it. Conversely, an individually imported profile will not change when you update another group. If you only have a screenshot, check whether it shows a QR code or menu instructions. Don't try to reconstruct an address you can't read in full. For details, see Share Links vs. Subscription Links.
Subscription URLs may contain access credentials, and anyone who knows the address may be able to read the group. Before pasting one, check that it has no extra quotation marks, spaces, or punctuation added by a chat app. Don't alter URL parameters or paste the address into an online decoder. If you need help, share the client name, the menu you used, and the type of error. In log screenshots, hide the full URL, account identifiers, node names, and server details. Use subscription labels to distinguish their purpose, and check the label before updating to avoid refreshing the wrong group.
Note your existing settings and test without the client
Before you start, note the system's current proxy settings, whether other network tools are running, and which local sites you need to access. If your device uses a proxy or automatic configuration script managed by your organization, preserve the existing settings; don't let the client override a managed network policy. First test a site you can normally reach without a proxy, then choose a page you can reopen as a connectivity check. A page left open in a browser doesn't necessarily mean the network is working. Open a URL that isn't cached and wait for it to load fully.
Keep your first test simple: enable just one client, one subscription group, and one known-good node. On desktop, test with a single app or the system proxy before enabling TUN. On Android, first establish the default VPN connection before changing per-app routing. Note the network and app you tested, such as home Wi-Fi and a browser. Results from different networks or apps aren't directly comparable. After switching networks, repeat the direct connection test before troubleshooting the subscription or routes.
Before moving to a new device, use the client's export or backup feature if available, and store the backup somewhere you control. If there's no export option, keep only the subscription source and essential custom rules on the device. Avoid copying all local port, permission, and network interface settings from the old device; its ports may already be in use on the new one. Start with the new device's defaults, then restore only settings with a clear purpose.
Windows: Install v2rayN, configure the system proxy, and use TUN
Choose the desktop or classic WPF edition
Go to Settings → System → About and check System type to confirm your OS and processor architecture. Then choose a package from the Windows downloads. For your first installation, try the desktop edition, which uses a cross-platform interface. If you prefer the classic menu layout, choose the WPF edition. Menu locations may differ, so when following an older guide, look for the menu name rather than matching an icon in a screenshot. Don't open both editions at once to compare them: they may compete for the same local listening port or overwrite the same system proxy settings.
Run the installer and follow the prompts, then open the client from the Start menu. If the window disappears after you close it on first launch, check the notification area and its hidden icons; some settings minimize the app to the system tray instead of quitting. To switch versions or free a port, choose Exit from the tray menu rather than just closing the window. If startup reports a missing runtime, check the requirements for your package. If the interface won't open, fix the installation first; there's no need to change subscriptions or routing yet.
Subscription groups: adding and updating are separate steps
Open Subscription groups, go to Subscription group settings, and add a group with a label and subscription URL. After saving, select the group and run its update command from the Subscription groups menu. If only one group has changed, update that group first so failures from other groups don't obscure the result. When nodes appear, select one and set it as the active server, then check the logs for startup errors. Clicking a row in the table may not switch the active server; confirm the active entry in the main window or status bar.
If the group is empty, check that the list filter and group selector point to the group you just added, then review the logs. If the log shows a timeout, troubleshoot subscription retrieval. If a response arrived but parsing failed, check whether you imported an individual share link or the server returned a login page. When setting up a new device, try updating directly first. Use the update-through-proxy option only if you already have a working connection and genuinely need it; otherwise, you can end up needing a node to download nodes.
Start with the system proxy; use TUN only if needed
Once the core starts normally, choose Set system proxy from the System proxy menu in the main window or tray, then reopen an app that follows the system proxy to test it. The system proxy tells apps the address of a local proxy; it doesn't force every process to send traffic through it. Browsers with their own proxy settings, command-line tools, and some desktop apps may ignore it. To configure an individual app manually, check the local listening port and supported protocol under Settings. Don't enter the server address in the app's local proxy field.
Consider TUN only when an app doesn't use the system proxy. Note the original system proxy settings, then enable TUN as prompted by the client, if your device allows it. If administrator access is explicitly required, save your work, quit, and reopen with the required permissions rather than running everything elevated all the time. Don't enable TUN alongside other virtual networking tools while testing. Check a regular webpage and a local service before testing the target app. If something goes wrong, turn TUN off and test again to see whether the issue comes from the virtual interface, route handling, or an existing connection.
If the logs say an address is already in use, check that no previous instance is still in the tray and no core process was started manually. If you can't identify the process using the port, switch to an unused local port and update any apps configured manually to use it. Don't terminate unfamiliar system processes. After changing the port, check whether your browser still has the old address saved; even if the core is listening again, the browser may continue sending requests to the old port.
macOS: Install v2rayN and configure network services
Download the package for your chip and launch it from Applications
Open About This Mac from the Apple menu. For a Mac with an Apple chip, choose arm64 from the macOS downloads; for an Intel Mac, choose x64. The packages target different architectures, so don't try them one at a time to see which works. Open the disk image, follow its instructions to move the app to Applications, and launch it from there. If you run it directly from the disk image, ejecting the image will break that launch path, and you may accidentally open an older copy later. If you already have the client installed, quit it normally before replacing the app.
If macOS says the app can't be opened, check whether the message is about the app's source, an incompatible system version, or the file itself. Source warnings and architecture issues require different troubleshooting; downloading a package for a different architecture won't fix a source warning. After confirming the app's source and package type, check System Settings → Privacy & Security for an app-specific prompt and follow your device management requirements. If your managed computer has restrictions, contact your administrator rather than disabling system-wide protections to install the app.
After importing a group, check that its status changes twice
In v2rayN, open Subscription groups and then the group settings. Add and save the URL, return to the list, select the new group, and update it. First, check that the expected entries appear in the group. Then set one as the active server and confirm that the core starts normally. If you're moving several groups from another computer, import just one to start with so multiple node names and routing rules don't complicate the first test. Before changing protocol fields, confirm you're using the original settings supplied by the provider. The client can't make the server's transport and security parameters match by itself.
If a subscription response arrives but no entries appear, check whether the content is a subscription format the client supports—not an account login page or a sharing page in a service dashboard. Import a single node from the clipboard; use the subscription option for a group URL. If only one node in a group won't start while others work, compare its protocol with the core's supported features. There's no need to delete the entire group. For more on the import and update sequence, see Importing Subscriptions on Desktop and Android.
Proxy settings may follow the network service, not the device
Once the core is running, select Set system proxy in the client and check the active connection. On macOS, the usual path is System Settings → Network → your current network service → Details → Proxies. Wi-Fi and Ethernet may use different network services. After unplugging or reconnecting a dock, the active proxy settings may change even if the client is still running. If automatic proxy configuration was already enabled, note how it was configured; don't leave behind manual proxy addresses you can't identify.
If a browser works but a command-line tool doesn't, check whether the tool reads the system proxy. If not, test with the tool's own proxy option. Enable TUN only if you need to connect an app that can't use the system proxy and your package supports TUN. Grant permission as prompted, then test a browser, a local network service, and connectivity after waking from sleep. If the connection fails after wake, turn the selected mode off and on again, then check whether the logs show a reconnection. There's no need to reinstall immediately.
Before quitting, restore the original proxy settings, turn off TUN, and then choose Quit from the app menu. Closing a window and quitting the app aren't always the same action. If web pages still won't load after the app quits, check the Proxies settings for the current network service for a leftover local address. Note the current settings before restoring them, then retry the same test page. If direct access still fails, check whether the Wi-Fi network needs reauthentication or has otherwise changed.
Linux: Install v2rayN, configure desktop proxy settings, and manage permissions
Check your distribution, package format, and architecture
Choose a package for your distribution from the Linux downloads. Ubuntu, Debian, and their desktop derivatives mainly use deb packages; Fedora and other rpm-based distributions use rpm. Once you've matched the format, check the architecture: x86_64 corresponds to x64 on the download page, and aarch64 corresponds to arm64. For a desktop system in a virtual machine, check the architecture inside the VM rather than relying on the host's details. Some containers and compatibility environments may also have a different userspace architecture from their host.
uname -m
cat /etc/os-release
Run the two commands above on the target system to check its architecture and distribution ID. If you have a graphical software installer, open the downloaded package with it and review any dependency prompts. Otherwise, use your distribution's native package manager to install the local package, specifying the actual path to the downloaded file. If dependencies are missing, check your distribution version and enabled repositories; don't mix in library files from another distribution. On first launch, search for v2rayN in the desktop menu. If no window appears, check the tray and app logs to tell whether the app is running in the background or failed to start.
Test with one group and one app first
Open Subscription groups, add the URL, give the group a clear label, save, update, and set an active server. If the update fails, note whether the logs indicate a retrieval failure or a parsing failure. If your command-line environment relies on another proxy to reach the subscription URL but the client's direct update fails, the requests are taking different paths. Note those environment differences before changing the update method. Don't assume the client can fetch a URL just because your terminal can.
On desktop Linux, system proxy behavior depends on the desktop environment and whether an app reads its settings. GNOME or KDE network proxy settings can help with checks, but shells, background services, and some sandboxed desktop apps may not share the same configuration. First test a graphical app known to use the proxy settings; then test the command line separately. The example below assumes 10808 is a working local SOCKS port confirmed in the client. Check your own Settings before testing.
curl --proxy socks5h://127.0.0.1:10808 --max-time 15 -I https://example.com/
This command uses a proxy for this request only. socks5h sends the domain name to the proxy to resolve, and doesn't change your login environment. A response confirms that this request got a result through the local proxy; it doesn't mean all desktop traffic is connected or that a particular routing rule was used. If the connection is refused immediately, check that the core is running and the port matches. If the request reaches the local port but times out, check the active configuration and relevant logs. Don't add global environment variables to system startup scripts as a first step.
Configure the virtual interface and permissions only if you need TUN
TUN usually creates a virtual interface and changes routing. Whether it works depends on the system environment and the client's permission setup. If the logs report an unavailable device or insufficient permissions, check whether you're in a container, virtual machine, or restricted session, then consult the instructions for your package. Don't run your entire desktop session with elevated permissions or clear existing routes or firewall rules to troubleshoot. Check your organization's requirements if you use managed network tools. If only one app needs access, a local proxy is often easier to undo.
Once you're confident the setup is stable, consider starting the app automatically at login. Desktop autostart launches the app in the logged-in user's session; it doesn't take over traffic for everyone as soon as the computer boots. First test the subscription, port, and proxy settings with a manual launch, then add one autostart entry. If a port conflict appears after login, check whether both the desktop autostart entry and an existing service are launching the app. Keep just one clearly managed launch method.
Android: Install v2rayNG, import subscriptions, and connect through VPN
Start with v2rayNG and choose a package your system supports
Choose v2rayNG from the Android downloads. Consider v2flyNG as an alternative only if you've confirmed that your existing configuration requires the V2Fly core. Most recent devices can start with the arm64 package, but installation also depends on whether the system userspace supports that architecture—processor hardware alone isn't enough to tell. If the system reports an architecture mismatch and the download page offers a universal package, try that next. If it reports a conflict with an existing app, check where that app came from and how it was installed before choosing a different architecture.
Open the downloaded package and follow the system prompts to allow installation from that source. If parental controls, a work profile, or an organization policy restricts the phone, check the device management requirements first. If an older app is installed, don't uninstall it just to resolve an installation conflict; uninstalling may erase local groups, custom rules, and per-app settings. Back up what you can export and confirm you can retrieve the subscription URL before deciding whether to migrate. On first launch, complete the basic setup without enabling auto-connect or background operation so you can verify each step in turn.
Add a subscription group, update it, then choose a node
In v2rayNG, open the menu and go to Subscription group settings. Add a label and subscription URL, save, return to the list, and choose Update subscription from the menu. The layout may vary by release, so use the menu names as your guide. When the update finishes, select the group, choose a node, and confirm that it's selected. If you only have a share link, use Import from clipboard or Scan QR code instead of adding it as a subscription URL. If you copied a long URL from a chat, check that the input field contains every line.
If an update fails, first check whether the phone's current network requires an additional sign-in through a browser. Then determine whether the server couldn't be reached or the response couldn't be parsed. If the update works on Wi-Fi but not mobile data, compare both networks on the same device with the same URL. Don't change the core, subscription, and node all at once. If entries suddenly disappear, check the selected group, filters, and whether the server's content changed. Keep any working entries before deciding whether to delete and add the group again.
Allow the VPN request, then check whether the app is included
The first time you tap Connect, Android will usually show a VPN connection request. Confirm it's from the client you just opened before allowing it. This uses Android's VPN interface to route device traffic; you don't need to copy the desktop System proxy settings or enter a desktop port in your Wi-Fi proxy settings. A VPN icon means the interface is up, but you still need to open a page in a browser to confirm connectivity. If Android says another VPN is already active, check the system's VPN settings and, if your device policy allows it, disconnect the conflicting VPN before testing.
If the browser works but a particular app isn't connecting as expected, check the client's per-app proxy settings and how the selected mode handles its app list. Some modes include only selected apps; others exclude them. For a clear test, switch to a mode whose behavior you can explain and reopen the target app so it doesn't reuse an old connection. The same app may have different settings in a work profile and a personal profile. Test it in the profile you actually use rather than relying on its icon.
If the network only fails after you close the client, check the system VPN settings for Always-on VPN or Block connections without VPN. These are system policies, unrelated to whether a subscription group has nodes. On a personal device, restore the settings that were in place before enabling them if needed. Follow the existing policy on a managed device. When switching clients, check whether the old connection or its policies are still active before authorizing the new client, so an old policy isn't mistaken for a failed installation.
Routing & DNS: traffic entry and split-routing rules
First check whether traffic is reaching the client
The system proxy and TUN determine how app traffic enters the client; routing rules determine which outbound path that traffic takes. If an app doesn't use the system proxy, editing the routing list won't connect it. If traffic has entered the client but matches a direct rule, bypassing the remote node may be expected. Start by testing an app that you know uses the local port, then compare how it behaves with the system proxy and TUN. Don't confuse switching routing modes with switching the system proxy.
When using TUN on desktop, watch for effects on local services, virtual network adapters, and other network tools. Admin consoles, LAN devices, and some VM networks may need to stay direct under your existing rules. Note how you normally access these addresses. If a local service becomes unreachable with TUN enabled, turn TUN off and test again to confirm that the traffic capture scope changed. Then decide whether to adjust a rule or use a per-app proxy instead. If traffic that the client didn't previously handle is now being captured, check the matching scope rather than adding a large set of unrelated rules.
Narrow rule matches by domain, address, and port
In v2rayN, open Routing settings and check which rule set is active. Save the original configuration before editing, and work on a copy if possible. Matching by domain is useful when the destination is a hostname; matching by address is useful when the app connects directly to an address or has already resolved it according to policy. An app may contact a service API, a static asset host, or a redirected hostname—not just the main domain in the browser's address bar. Start with one reproducible request, check the destination the client sees, and then choose the right type of condition.
Put specific exceptions before broader matching rules. Once a request matches an earlier rule, later exceptions won't be checked. Don't put an overly broad catch-all at the top of the list, and don't rely on a commonly used port alone to identify a service; unrelated services may use it too. After editing, check that the rule points to an outbound that actually exists. The direct or proxy names shown in the interface are tied to outbound tags in the configuration. Don't copy a tag from another configuration if it isn't defined on your device.
| Value | Effect on route matching |
|---|---|
AsIs | Does not resolve the target domain for rule matching; an available address can still be matched by address rules. |
IPIfNonMatch | If the original target doesn't match, tries to resolve the domain and match using the resulting address. |
IPOnDemand | Resolves the target domain first when address conditions need to be checked during matching. |
These values control when the core resolves domains while evaluating routes; they don't guarantee that an app's DNS lookups will use the core's DNS. If an earlier wildcard rule has already matched the request, don't expect IPIfNonMatch to continue to address-based rules. Before changing this setting manually, check which core and version the client uses and what it supports. First observe which rules match domain-based and address-based requests, then compare the strategy settings. This field isn't a general connectivity switch.
Set up DNS, then verify the route with the same request
If one domain won't load while other sites work, distinguish a DNS lookup failure, an unsuitable address, and a connection failure after an address was returned. Browsers may use their own secure DNS, while command-line tools may use the system resolver, so their results can differ. Keep the app and network the same while testing one DNS or routing setting at a time. If you need to adjust the core's DNS, see the DNS Split-Resolution Guide to decide which domains should use which resolver.
After saving a rule, make a new request so an existing connection doesn't bypass the change. If you can see match details, check the target, rule, and outbound. If not, test a local target that should go direct and another target that should use the proxy. If only one fails, check its matching condition and outbound. If both fail, return to the traffic entry settings. Once the change works, note the rule's purpose so you can undo it later without guessing which row caused the problem.
Configuration FAQs: troubleshoot by where the error occurs
Update failed: first check whether any content was retrieved
A timeout, a domain lookup failure, an access denial, and a parsing error each call for different troubleshooting. For a timeout, first check whether the current network can make a direct connection, then confirm whether the update is configured to fetch directly or through a proxy. If access is denied or the URL is invalid, return to the subscription's original source and check the URL and account status. Don't keep retrying at high frequency. If the request succeeds but parsing fails, check that the response uses a supported subscription format. A login page or service notice can load successfully, but it isn't an importable list of nodes.
Some providers change entry names, order, or count after an update. Don't assume an entry with the same name is still active, or that an empty list means the service is down. Clear any search filter, select the right group, and check the update log against the actual entries. If the update changed the active configuration, select a known node again. If you need to keep the old configuration, back it up before updating so you have a reference if both the network and configuration change.
Core won't start: fix the first meaningful error
Open the main window's logs and look for the first error after you click Connect or switch nodes. For a port conflict, check for duplicate instances and verify the port setting. If a core component is missing, check that the installation is complete and the program is running from the right location. If protocol parameters aren't recognized, check that the entry's transport and security options match the current core. Repeated retries can produce many similar log lines; later connection failures may be caused by the first error. Don't change the remote configuration to fix a local listening failure.
If only a custom configuration fails to start, switch to a normally imported entry that has worked before. If that entry works, narrow the issue to custom fields, reference tags, or core compatibility. If both fail, check process permissions and local ports. A copied configuration snippet may be only one section, not a complete working configuration. If you're unsure about security settings, ask the configuration provider for a compatible set instead of disabling validation one option at a time.
Connected but apps can't reach the network: check that they use the same path
A working browser doesn't mean other apps use the same connection path. Check whether the failing app reads the system proxy, is excluded by Android's per-app settings, or runs in an isolated session. If just one destination fails, check its DNS lookup and routing match. If everything fails, check the active server and local entry point first. Test with a new request in the same app and note whether the network changed. Don't use an earlier screenshot of a successful connection to infer the device's current route.
If the problem only occurs after changing networks, first test whether the current network can reach a page directly and check for a sign-in requirement; some failures happen before the client starts. If regular pages work but one app times out, compare the protocol it uses with the connection mode. For example, if it needs UDP, check that the client entry, node configuration, and remote server can all handle that traffic. Enabling a local option alone doesn't prove the full path supports UDP.
Why does the latency test pass when the app still won't load?
A latency test usually checks only its test destination or the connection handshake. Confirm the failing app uses the client, then check the actual domain it contacts and the outbound it takes. Different targets can produce different results.
The internet still doesn't work after quitting. Should I reinstall?
First check for a leftover system proxy, TUN interface, or system VPN policy. Restore the original settings and test the same page directly. If the issue occurs only after quitting the app, reinstalling isn't the first step.
One subscription group has an error. Should I clear all client data?
Keep other working groups and check the affected group's URL and update result. Reproduce the issue with a separate group before troubleshooting the one that fails. Don't use a full reset as a substitute for finding the cause.
If you still can't identify the cause, describe the issue in one reproducible sentence: the operating system, client, connection mode, action, and type of error. Add whether you recently updated or changed networks, then include the first relevant error with sensitive details removed. This is more useful than a full-page scrolling screenshot for identifying whether the problem is subscription retrieval, core startup, traffic entry, or routing.
Updates & recovery: preserve working settings and a way back
Keep client updates, core changes, and subscription updates separate
A client update can change the interface and local behavior; a core change can affect supported protocols, transports, and routing fields; a subscription update changes the entries supplied by the service. Even if all three options appear in one screen, they do different things. To get new nodes, update the relevant subscription group. To fix a client issue, note the current package type and connection mode, then choose a package for the same platform and architecture from the client downloads. If you're also changing package type, treat it as a migration rather than assuming you can install over the existing version.
Before updating, keep one configuration that connects successfully and note the system proxy state, active core, listening port, routing rule set, and whether autostart is enabled. If the client has a backup feature, save a clearly labeled local backup and confirm that you can restore it from the expected menu. A backup isn't just program files: subscription groups and rules are usually user data, while the app itself can be installed separately. Check for credentials in the backup before archiving it. Don't attach it to a support log or store it somewhere publicly accessible.
Test the app first, then restore custom settings
When upgrading or switching devices, turn off the active proxy entry and quit the old instance normally before installing the new package. After launch, check that the interface opens and the core starts. Then test one known configuration with a single app. Once it works, restore extra groups, rules, TUN, or per-app filters, one category at a time. If the default setup connects but fails after you restore a routing rule, you can investigate that rule rather than searching through an entire migrated configuration.
After a desktop OS upgrade, recheck network service names, system proxy settings, and virtual interface permissions. After switching Android devices, recheck VPN permissions, background restrictions, and which apps are available in work and personal profiles. Importing data from an old device doesn't automatically grant the new one the same system permissions. Verify the connection in the foreground first, then test after sleep or a locked screen. Enable auto-connect or extended background operation only after both situations work as expected.
Roll back one step at a time
If an issue starts after changing a rule, switch back to the previous rule set. If it starts after enabling TUN, turn TUN off and return to the connection mode you already tested. If you changed a listening port and only some apps fail, correct their local proxy addresses first. Repeat the same test after each rollback. If the issue is resolved, don't also delete the subscription and app data. Note the change you reverted and retry it separately later if needed. Reinstall or clear old settings only if the old and new environments really aren't compatible and you have a usable backup.
Clearing all system network settings isn't the right fix for every connection problem. If the system is still offline after the client quits, restore the proxy settings you recorded before enabling it and check for an active VPN policy. If settings are restored but direct access still fails, troubleshoot the network itself. Restore organization-managed settings to the state required by your administrator. Before uninstalling, quit running instances, restore network settings, and keep any user data you need. Remove the app through the system's app manager so you don't discover afterward that your proxy still points to a port that no longer exists.
Keep a short record of common settings, separating essentials from optional ones. Essentials might include the active group, core, and entry point used for a single-app test; optional settings might include autostart and extra rules. When setting up a new device, follow the connection steps in the Getting Started Guide to verify the essentials, then use this page for specific settings. For unfamiliar fields, check the Glossary instead of keeping a full set of screenshots that can quickly go out of date.