V2Ray Setup GuideSubscriptions, proxies, and troubleshooting

Before you begin: platforms, subscriptions, and backups

Know the difference between the client, core, and server

v2rayN manages desktop node lists, subscriptions, proxy settings, and core processes. v2rayNG and v2flyNG provide graphical clients for Android. The core handles protocols, routing, and connections; a node contains the settings for a remote server. Installing a client doesn't give you a node to connect to. Before you start, get a valid subscription URL, share link, or complete configuration from a service you're authorized to use.

For desktop, start with v2rayN. On Android, v2rayNG with the Xray core is a good starting point; consider v2flyNG if you need the V2Fly core. The same protocol name doesn't guarantee compatibility with every extension field: the transport, security settings, and core capabilities must all match. If an import succeeds but the connection fails, check which core the configuration requires before trying another client.

Choose an installer that matches your processor architecture. This guide covers the x64 desktop and WPF builds of v2rayN available on the download page; macOS builds are available for Apple Silicon and Intel; Linux packages vary by architecture and format; Android builds include arm64 and universal options. Operating system, processor architecture, and application interface are separate considerations. A matching OS name in a filename isn't enough to confirm compatibility.

Check your subscription and system

Treat subscription URLs like passwords: they often contain access credentials. When copying one, check for leading or trailing spaces, line breaks, or punctuation added by a messaging app. Hide the URL, user identifiers, and node credentials in screenshots. An update can fail because the URL expired or returned a web page; a failure message alone doesn't mean the client is broken. Share only a brief error summary in public forums, never your full private URL.

Before connecting, check that your system date, time, and time zone are correct, and enable automatic time synchronization. Certificate checks and some protocol handshakes depend on accurate time; a large offset can make secure connections fail. Also check that your network can reach local services, whether you need to sign in to the network first, and whether another proxy or virtual network adapter is running. For your first test, use just one traffic-routing method so you can see where requests go.

A subscription, a share link, and native JSON are different kinds of input. Subscriptions usually update multiple nodes; a share link typically describes one node; native JSON may define a complete setup with inbounds, outbounds, routing, and DNS. Use the import option that matches the input type. Don't try to update a subscription with a full configuration file. See Subscriptions and Share Links for details.

Start with a minimal setup you can roll back

For your first setup, you need one working node, one way to route traffic, and a clear routing mode. Don't add custom DNS, complex rules, or app-specific routing yet. Test subscription updates, node connectivity, and browser access separately, then add settings one at a time. This makes each change easy to compare and lets you return to the last working state if something breaks.

Before upgrading or migrating, use the client's backup or export feature to save your configuration. For a manual backup, fully quit the client first, then copy its actual configuration directory. Data locations vary by installation method, so check the app or its logs instead of relying on an old path you found online. Include subscription groups, routing settings, and any custom configuration you need. Restrict access to the backup to protect node credentials.

Windows: Install v2rayN and set up the system proxy

Choose the desktop or classic WPF build

Choose v2rayN from the Windows downloads. The desktop build uses a newer cross-platform interface; the WPF build keeps the classic desktop experience. They don't connect to different node services. Choose the interface you're familiar with, or start with the desktop build if you're new. The download page offers x64 builds. Before installing, check your system information to confirm your processor architecture and that your version of Windows meets the requirements.

Run the installer and choose an installation location. If you downloaded a portable archive, extract it fully to a permanent folder before launching the main program; don't run it from the archive preview. Avoid temporary download folders, and don't copy only the main executable if the package includes other resources. The interface may open even when a core, rule data, or runtime dependency is missing, but connections can still fail to start.

You don't need administrator privileges for a basic system proxy test. Start the client as a standard user and check the logs to see whether it can open a listening port, read the configuration, and start the core. If a security alert blocks a component, verify which file and action triggered it; don't disable your security software entirely. Handle any permissions needed for TUN separately. Elevated privileges won't fix an incorrect path or port conflict.

Import a subscription and connect for the first time

In subscription management, add a group, enter a recognizable name and the full URL, save it, then update that group. Menu labels vary, but adding a subscription and fetching its nodes are usually separate steps. After the update, confirm that nodes appear in the group and check the logs for authentication errors, parsing errors, or an unexpected response format. A newly created but empty group doesn't mean the subscription was imported.

Choose a node from the new group, set it as active, and test a real connection. A latency check only shows that a particular probe received a response; it doesn't confirm a successful protocol handshake, access to your destination, or working DNS. Start with a node that passes the available test and note its name and protocol. If every node in the group fails, check the subscription and system time. If only one fails, try another in the same group before changing global settings.

Start the core, then enable the system proxy so apps that follow system settings send traffic to the local listening address. The mode's exact name depends on your version; confirm that the proxy is set at the system level and that the client is still running. Then open a browser to a known working test page. Check the exit IP and client logs to confirm the request used the expected outbound. See First Connection and Proxy Verification for detailed testing steps.

System proxy limits and TUN troubleshooting

A system proxy doesn't route traffic from every program. Some command-line tools, games, and standalone network components need their own proxy settings, and browser extensions can override the system choice. If a browser works but another app doesn't, check whether that app reads system proxy settings, what transport it uses, and whether it has its own network configuration. One app bypassing the proxy doesn't mean the active node is unavailable.

If you need broader traffic coverage, check whether your v2rayN version, selected core, and system support TUN. Before enabling it, note the current system proxy and network settings, then grant any required permissions or configure the necessary components. Disable other virtual network routing tools and test local network access, DNS, and destination connectivity. TUN determines how traffic enters the client; routing rules still decide whether it goes direct or through a proxy.

If the network stops working after you quit, first check whether the Windows manual proxy still points to a local port that is no longer active. Restore the previous settings, then test again. If a port is occupied, use the logs to identify it and close duplicate client instances or change the local listening port; don't change the remote server port. Check upgrades, rule changes, startup paths, and launch-at-login settings separately rather than treating them all as node failures.

macOS: Choose the right build and manage network permissions

Install v2rayN for your processor

Open About This Mac to check your chip, then choose the matching v2rayN build from the macOS downloads. Apple Silicon uses the arm64 build; Intel uses x64. Don't guess based on the computer's appearance, purchase date, or name. A mismatched build may not launch, may require a compatibility environment, or may cause component errors. Check your download selection before changing your subscription.

Open the DMG and follow the installer to move the app into your Applications folder, then launch it from there. Don't keep running it from a mounted disk image: ejecting the image, deleting the download, or signing in again may break the launch path. If macOS shows a security warning on first launch, confirm the app's source and the file you downloaded, then use the system's Open Anyway option. There's no need to disable system-wide security settings.

A window opening doesn't mean every network permission is in place. macOS may request authorization only when the app changes proxy settings, starts a background component, or routes traffic through TUN. Read each permission prompt and grant only what's needed for the feature you're using. If you previously denied a request, check the relevant item in System Settings. Repeatedly clicking Start won't grant permission, and an authorization error doesn't mean the remote node is unreachable.

Subscriptions, system proxy, and testing

Add a group in subscription management, save the URL, update the group, and confirm the node list refreshes. When copying a URL between devices, check for spaces or line breaks on the clipboard. If the same URL works elsewhere but returns no nodes here, check the update logs and network access conditions. Import share links through the appropriate option; handle full native configurations using a custom configuration workflow supported by the client.

Choose a node and start the core. First confirm the connection test completes, then enable the system proxy. macOS proxy settings are associated with network services; Wi-Fi, Ethernet, and other services may each have their own state. If behavior changes after switching networks, check the service you're actually using, not the proxy toggle for another interface. Verify the active network settings in macOS even when the client says the proxy is enabled.

Whether a browser uses the system proxy also depends on its own configuration. For a clear test, temporarily disable extensions that override proxy settings, use one routing method, then visit a known reachable page and check the logs. A page loading doesn't prove all traffic was routed through the proxy; it may have connected directly. Check routing logs and exit IP for destinations that should use the proxy. Not every site needs to show the same exit IP.

TUN, sleep, and network changes

If an app ignores the system proxy, consider TUN if your client and system support it. Before enabling TUN, check for other network filters, virtual adapters, or tunnels that could also route traffic, and avoid having multiple tools take over the default route. After granting permission, test basic DNS resolution, destination access, and local network access. If the whole computer loses connectivity, disable TUN to return to the system proxy baseline, then review routing and DNS.

After waking from sleep or switching from Ethernet to Wi-Fi, existing connections may fail even though the local listener is still running. Check that the base network is back, then restart the connection or core; there's no need to delete the subscription right away. If only DNS fails, check which DNS path is actually in use by the system and client. If all connections time out, check node reachability, network sign-in status, and any stale traffic-routing settings.

When moving configurations, use the client's export and import features if available. Don't overwrite the app's entire runtime directory with one from another computer. Executable components may not work across architectures, and absolute paths in the configuration may no longer be valid. Before upgrading, keep copies of your subscriptions, routing settings, and custom configuration. After upgrading, check that the core starts, the system proxy works, and required permissions are in place. When quitting, verify that the proxy has been restored so the system doesn't keep sending traffic to a stopped local service.

Linux: Packages, desktop proxies, and permissions

Check both package format and architecture

Choose v2rayN from the Linux downloads. Choose deb for distributions that use deb packages and rpm for those that use rpm, then select x64 or arm64. Your desktop environment doesn't determine the package format, and the processor brand alone doesn't confirm the architecture. Check your distribution and architecture in system information first. If you need a command-line check, the read-only command below won't change your system settings.

uname -m
cat /etc/os-release

x86_64 generally corresponds to x64 on the download page, and aarch64 to arm64. Once you've confirmed the architecture, open the downloaded package in your graphical software installer, follow the prompts to resolve dependencies, and complete the installation. Even the right package format can require newer system libraries, so read the specific dependency error from the installer. Don't force installation by ignoring errors or use a package for a different architecture as a workaround.

After installation, launch v2rayN from the app menu and check that the graphical interface, configuration saving, and core startup all work. Tray support varies between desktop environments. Check the process and logs to see whether the app is still running after you close its window; don't rely on the tray icon alone. If the interface won't start, investigate runtime dependencies or the graphical session first. These issues occur before the client reads nodes and aren't directly related to your subscription.

Import subscriptions and understand desktop proxy limits

Add a subscription group, save the URL, update it, and select an active configuration once nodes appear. On Linux, distinguish the network environment used by the graphical client from the one used by your terminal. Terminal access to a subscription URL doesn't mean the graphical app inherits the same proxy environment variables. If an update fails, check the client logs to see whether it uses a direct connection, the system proxy, or another configured route. Avoid a loop where the client depends on its own listening port to reach the subscription.

After enabling the system proxy, check the host, port, and bypass list in your desktop's network settings. Desktop environments don't all implement system proxies the same way; some apps use their own settings or environment variables inherited at startup. If a browser works but a terminal tool doesn't, check how the tool handles proxies. Conversely, configuring a proxy in the terminal doesn't mean the entire desktop session is routed through it.

For local HTTP and SOCKS connections, use the ports displayed by the client instead of copying numbers from someone else's setup. An app that requires SOCKS can't use an HTTP proxy address directly. Whether DNS is resolved locally or remotely also depends on the app and protocol. For your first test, use one app and one routing method. Confirm that the request appears in the logs before expanding coverage; don't change desktop proxy settings, terminal variables, and client routing all at once.

TUN permissions and multiple network interfaces

TUN usually requires permission to create a virtual interface and change routes. Availability depends on your v2rayN version, core, and system environment. Follow the client's permission setup instead of running the entire graphical app with elevated privileges all the time. Insufficient permissions, an unavailable device node, and a routing conflict are different problems; use the logs to identify the failing stage. Containers, restricted sessions, and customized systems may also have different network capabilities from a standard desktop.

If you're using Ethernet, Wi-Fi, container networking, or a virtual machine at the same time, check whether you need direct access to local network addresses. Taking over the default route can change how you reach the local network; add explicit routing for private subnets you need instead of disabling the system firewall. DNS may be managed by the system resolver, a network manager, or another component. Before editing settings manually, find out which service currently manages them.

If command-line networking fails after you stop the client, check whether the terminal session still has proxy environment variables pointing to a local port. If only desktop apps fail, check whether the desktop proxy is still enabled. After an upgrade, recheck installation dependencies, configuration directory permissions, and rule data paths. Don't copy core files built for another architecture when migrating. Before uninstalling, restore the original network routing settings so you don't leave behind a broken proxy route.

Android: Import subscriptions and route traffic through VPN

Choose v2rayNG or v2flyNG

Choose a client from the Android downloads. v2rayNG uses the Xray core and is the recommended starting point in this guide. v2flyNG uses the V2Fly core and is suited to configurations that require it. Their settings and core capabilities aren't identical. For configurations with specific extension fields, first confirm that the target core supports those fields. An import succeeding doesn't guarantee the connection will work.

For most arm64 devices, choose the arm64 build. If you're unsure of the processor or system architecture, check system information before considering the universal build. A processor's capabilities don't necessarily match the architecture used by the system's user space. If the installer can't parse the package, check device compatibility, system requirements, and whether the download completed properly. Try the universal build only after those checks; don't confuse an installation issue with a remote server problem.

During installation, follow the system prompts to let the current download tool or file manager install apps. You can revoke that permission afterward if you like. If an update fails because the signature doesn't match, check where the existing app came from, back up your subscriptions and configuration, and then decide how to migrate. Uninstalling immediately may remove groups and custom rules. Before updating, also note a working node and routing mode so you can test the same setup afterward.

Import nodes and grant system permission

Copy the subscription URL, add a record in subscription settings, enter a name, save it, and then update. Use the appropriate clipboard import option for share links, and check whether a QR code contains a node or a subscription URL. If no nodes appear after an update, check the logs and group filters. Importing just one node isn't necessarily a failure; the input may have been a single-node share link rather than a subscription with multiple nodes.

Select an active node from the list. When you start a connection, Android will ask for VPN permission. The VPN interface routes device traffic to the local client; it doesn't confirm that the remote node is reachable and isn't the same feature as a desktop system proxy. After granting permission, check the client status and logs, then visit a destination to test the connection. A VPN icon in the status bar only confirms that the interface is up, not that the protocol handshake or destination access works.

Standard VPN use on Android doesn't usually require extra system-level privileges, but a user environment generally can't let two standard VPN apps route traffic at the same time. Check whether another network tool is using the VPN interface before starting this client. If the connection button works but another app quickly takes over the interface, resolve the conflict first. Don't keep switching nodes and DNS between clients; it makes testing unreliable.

Per-app routing, background restrictions, and network changes

For per-app routing, check whether the list means “only proxy selected apps” or “bypass selected apps.” The modes are opposites, so selecting the same app can have different results. Reconnect as required after changing the setting, then test in the target app; existing connections may continue using the old route. Make sure the browser is included in your test, or its direct connection won't tell you whether the node is working.

Some devices restrict apps after the screen turns off or they have been in the background for a while. If the connection works with the screen on but drops when it's off, check battery optimization, background activity, and auto-start settings, then confirm that the client keeps its connection alive. An ongoing notification and VPN icon can help you check status, but also review the logs. If you enable always-on VPN or block connections outside the VPN, the whole device may appear offline when the node fails. Understand these settings before using them.

After switching from Wi-Fi to mobile data, you may need to reconnect; subscription access and DNS conditions may also change. First confirm that the new network can reach basic services, then reconnect to the same node. If only one app fails, check per-app routing and its cache. Keep v2rayNG and v2flyNG configuration exports separate. When migrating, check protocol, security, and routing fields rather than assuming similar interfaces mean the configurations are fully compatible.

Routing and DNS: From traffic entry to outbound

Decide what to route before choosing an outbound

System proxy settings, TUN, and the Android VPN interface determine whether a request reaches the client. Routing rules decide which outbound handles it once it arrives. Enabling TUN doesn't mean all traffic must use the proxy, and global proxy mode can't control apps whose traffic never reaches the client. For troubleshooting, first check whether the request appears in the core logs, then inspect the matching rule and outbound. This helps distinguish an entry-point issue from a routing rule issue.

Routing rules are usually evaluated in order; the selected core determines the exact behavior. Place specific domain exceptions before broader rules, match local network rules to your actual needs, and keep a clear fallback policy. When multiple rules match the same destination, don't infer the outcome from their names. Check the match fields, order, and final outbound. Reconnect after changing rules so an existing connection doesn't affect your test.

This partial Xray configuration shows how to route private addresses directly. It's not a complete configuration: it requires an outbound named direct and usable GeoIP data. A graphical client may generate equivalent settings, so use its routing editor when possible instead of editing generated files. If your changes are overwritten at the next launch, update the setting that generates the file.

{
  "routing": {
    "domainStrategy": "AsIs",
    "rules": [
      {
        "type": "field",
        "ip": ["geoip:private"],
        "outboundTag": "direct"
      }
    ]
  }
}

Domain rules, IP rules, and DNS resolution

geosite references a domain collection; geoip references an IP address collection. They aren't interchangeable keywords. Collection names must exist in the data files currently loaded and use a format supported by the core. With domain rules alone, traffic to an IP address may not match. With IP rules alone, the DNS resolution path can affect the result. Combine the two rule types for a specific purpose rather than adding them indiscriminately.

Distinguish DNS requests made by apps, system DNS resolution, and resolution performed by the core for routing or connections. With a system proxy, an app may resolve a domain locally and pass the resulting address to the client, or send the domain for the proxy to resolve; behavior depends on the app and proxy protocol. Enabling a DNS option won't automatically unify every resolution path. Check whether the target app uses encrypted DNS or cached results.

This example shows a partial DNS configuration for Xray. localhost uses the system resolver; queryStrategy limits the address types queried. It's an explanation of the fields, not a universal solution for every network. IPv4-only resolution may avoid some address-family issues, but it also rules out usable IPv6 paths. Before changing it, check which address families your node, destination, and local network need.

{
  "dns": {
    "servers": ["localhost"],
    "queryStrategy": "UseIPv4"
  }
}

Configure DNS for your destinations, not by piling on servers

If you need different DNS resolution for different domain categories, first decide which domains should use local resolution and which should follow another path. Then check how DNS requests themselves are routed. Adding a remote DNS server doesn't mean traffic to it already goes through the proxy. If the node server uses a domain name, make sure it can be resolved before the connection starts to avoid a loop where you need the proxy to resolve the proxy server's address.

Updating rule data and updating a subscription do different things. A subscription refreshes node settings; rule data updates domain or IP collections. One update won't fix the other. If routing fails for a category of sites, test one specific domain and check that the rule name exists, is in the right order, and its data file is loaded by the core. See Routing with geosite and geoip for a complete walkthrough.

Diagnose DNS issues by symptom. If a domain fails but a known IP works, start with DNS. If the domain resolves but the handshake fails, check security settings and connectivity next. If only certain domains use the wrong outbound, check rule matches and cached results. After changing DNS, reconnect and clear caches using the system's supported method. Don't disable certificate verification to keep a connection working. See Split DNS Configuration in Xray for an in-depth guide.

Common configuration issues: Logs and rollback steps

Save the current state, then narrow down the problem

At a minimum, record your operating system, client, selected core, traffic-routing method, and the step where the failure occurs. Include only the relevant log lines from startup to the error, and hide subscription URLs, credentials, and private server details. Save your current settings and change one variable at a time. If you change nodes, rewrite DNS, enable TUN, and update rules all at once, you won't know what fixed the issue and may have trouble reproducing it.

Start with the first clear error in the logs, not just the final exit message. A configuration read error can prevent the listener and connection from starting. A port conflict can stop the core from launching. A handshake error means the process reached a later connection stage. Identify whether the issue is in configuration, listening, DNS, the handshake, or routing, then choose the next step. This usually provides more useful clues than reinstalling.

Use the table below to guide your checks, not to map one error message to one definite cause. The same timeout can result from a network issue, an unreachable server, DNS, or a routing loop. Read the logs alongside what you're seeing: Can other nodes connect? Do other apps work? Does the base network recover when routing is disabled? These comparisons are more useful than a single error message.

Troubleshoot installation, subscriptions, and core errors separately

If installation fails, check the platform, architecture, package format, system requirements, and write permissions. If a runtime component is missing, verify the complete installation instead of replacing only the main executable. If the app won't start after an upgrade, use a backup and a minimal configuration to determine whether the runtime environment changed or the old configuration is incompatible. See Troubleshooting Core Startup Errors in the Logs for help interpreting specific messages.

When a subscription update fails, distinguish between an inaccessible URL, rejected authentication, unparseable content, and nodes hidden by a filter after updating. Copying the URL again may fix a typo, but it won't renew an expired service. Repeatedly deleting groups can also remove local notes. After an update succeeds, node names may have changed and manual selections may no longer apply. Check the active node instead of assuming a node still shown in the list is current.

For a failed handshake, check the server address, port, protocol, transport, security settings, and any required server name. Use subscription-provided parameters as a set; don't change just one to get a temporary connection. For certificate errors, check the system time and name match. Skipping verification changes the security boundary and isn't a general troubleshooting step. Correct a field only when you've confirmed it doesn't match the server's requirements, then test again.

Common questions and a recovery baseline

To restore a baseline, keep a backup, disable new custom rules and DNS settings, select a known working node, and enable only one traffic-routing method. Repeat the checks in the preparation section and find the last step that worked. Once the connection is stable, restore routing rules and app exceptions one at a time, recording each change. To repeat the first connection steps, return to the Quick Start Guide. To change your build or platform, check the options on the downloads page.