V2Ray Setup Guide: From Installation to Routing

Use this page as a configuration reference, organized by stage. For your first connection, start with the Quick Start Guide: import a configuration, choose a proxy mode and verify the connection. Then come back to learn which traffic each setting affects. You can also jump straight to a chapter if you have a specific issue.

1. Core Concepts: Clients, Cores and Protocols

Follow a request through the inbound and outbound paths

Break each request into three stages: the app sends it to a local entry point, the core selects an exit based on its rules, and that exit connects to the destination. A webpage loading successfully proves only that this request completed; it doesn't tell you which exit it used. Likewise, a client window opening normally doesn't prove that the core has started or that the app has sent a request to it. Troubleshooting from the first stage onward is more effective than repeatedly changing settings.

An inbound is the interface through which the core receives requests. Desktop apps can explicitly use a local HTTP or SOCKS proxy; a system proxy tells apps that honor system settings where to send traffic. An outbound determines how the core handles a request, commonly by proxying it, connecting directly or blocking it. Routing rules select an outbound after a request enters, so changing them won't make apps that bypass the client connect automatically. The chapters below help you verify both whether traffic gets in and which route it takes out.

VMess is a protocol; transport settings are something else

Project V provides the ecosystem context for understanding V2Ray. V2Fly and Xray are related open-source core families, while graphical clients turn subscription entries, routing rules and proxy options from the UI into core configuration. Similar menu names don't guarantee identical output. Nor does one client importing an entry mean that every core it can use will run it. A successful import only shows that the client recognized at least part of the input.

VMess and VLESS define how a proxy connection exchanges data and identifies users. Transport describes how that data is carried, for example over TCP or WebSocket; TLS provides transport protection and verifies the peer's identity. The address, port, protocol, transport path and server name each matter. If the port is reachable but the session fails, check the full set of parameters. Don't mistake a resolvable address for a compatible protocol, or disable certificate verification just to clear a warning.

Know the difference between share links, subscriptions and full configurations

A single share link usually describes one connection and is suited to a one-time import. A subscription URL points to a list of entries that the client fetches and updates as a group. A full configuration may also include listen addresses, routing, logging and DNS settings. These are different levels and aren't interchangeable. Check which type the provider supplied before choosing an import option. Both subscription URLs and individual links may contain credentials. When reporting an issue, describe the format, error and steps to reproduce it—never paste the original link.

DNS lookups can happen at several points. An app may resolve a domain first; the core may resolve it to match IP rules; or a proxy outbound may send the domain to a remote resolver. Seeing only an IP in the logs doesn't prove the original request had no domain—the app may have resolved it before the request reached the client. Trace the full request path first, then ask where the domain is still visible. That tells you whether to check domain rules, address rules or the app's own DNS settings.

2. Choosing a Client: v2rayN, v2rayNG and v2flyNG

Choose an app for your device, then a core for your configuration

For desktop, start with v2rayN. If you need to move between desktop platforms, check the desktop build for each platform. On Windows, if you're used to the classic interface, compare the WPF edition's menus and workflow. For Android, v2rayNG with the Xray core is the usual choice. If your configuration is specifically designed for a V2Fly environment, consider v2flyNG as an alternative. Don't start by asking which client has the lowest latency. Latency also depends on the network, server and test method; first confirm that the features you need work.

Choose a platform, client and installer
PlatformClientCheck before downloading
Windowsv2rayNThis download is the x64 option. Choose between the cross-platform desktop edition and the classic WPF edition.
macOSv2rayNChoose arm64 for Apple Silicon or x64 for Intel.
Androidv2rayNG; v2flyNG as an alternativeCheck which app architectures are supported, then choose arm64 or a universal package as needed.
Linuxv2rayNCheck whether your distribution uses deb or rpm packages, then choose x64 or arm64.

Don't guess the architecture from the device name. A desktop operating system labeled 64-bit doesn't necessarily mean x64; it could be arm64. In Windows, check System type under Settings → System → About. In macOS, check the chip or processor under About This Mac. On Linux, use the command below to check the machine architecture reported by the system; x86_64 usually means x64, and aarch64 means arm64. If you're installing the app in a virtual machine, use the guest system and its architecture as your reference.

uname -m

Think about compatibility as three separate questions

First, can the app import the format supplied by your provider? Second, can the selected core run the protocols and transports used by the entry? Third, does the app support the local access method and routing features you need? For example, if you need to proxy a desktop app that ignores system proxy settings, prioritize a local proxy entry point or TUN—even if both clients can import the same subscription. If you only need a browser to access specific resources, there's no need to enable both access methods.

When moving to another device, reimport a subscription from a trusted source first, then recreate only the local rules you need. Don't copy the entire client setup over another operating system. The original may contain paths, outbound names, listen ports and startup settings specific to the old system. Devices can share server entries without sharing local network settings: desktop LAN ranges and printer addresses often differ from the networks used by mobile devices.

Try the client with your actual use case

Choose a package for your device on the client downloads page. Import one known-good configuration into a single app. Verify that it starts, receives requests and returns the expected response before deciding whether to migrate the whole group. If you have both Android clients installed, disconnect one before testing the other; otherwise, a change in which app owns the system VPN may look like a crash. When comparing desktop clients, don't let both apps bind to the same local listen port at once.

If your provider supplies only a complex core configuration, check that it's supported by the import method in your client. Being able to read share links doesn't mean the app can import arbitrary JSON. Even when a custom configuration option is available, the app may only start the core and leave some settings unmanaged. For interface and ecosystem differences between the three clients, see our client comparison. Save features you don't need yet for when a real use case comes up.

3. Installation and First Launch: Check Your Local Setup

Desktop: verify that the client starts on its own

Install the package that matches the operating system, architecture and package type listed on the downloads page. On Windows, launch the desktop or WPF edition you chose. If a runtime warning appears, note the framework name and required architecture, then install the matching runtime. Reinstalling repeatedly is no substitute for reading the error. If you get a permission error when saving settings, check whether the configuration directory is writable and whether it's in a managed location. Running the app as administrator long-term isn't a fix.

On macOS, choose the package that matches your chip. If a security warning appears the first time you open the app, verify its source and read the specific reason given by the system; follow the system's approved process rather than disabling security protections globally. On Linux, choose the package format for your distribution and let its package manager handle dependencies. If dependencies can't be satisfied, check the distribution and software repository status first. Forcing installation past missing dependencies can turn an installation error into a hard-to-diagnose startup failure.

On first launch, leave startup connection, system proxy and TUN disabled. Check that the interface opens, settings can be saved and they can be read back after reopening the app. If the window closes but a tray icon remains, the process may still be running. Before upgrading or replacing settings, quit from the tray and confirm the process has exited. An older instance holding a port may let a new instance open while preventing its core from starting.

Android: distinguish installation permission from VPN permission

Opening the installer doesn't mean the system has allowed the app to create a VPN. When you connect for the first time, a system authorization prompt may appear. Read it and confirm that the expected app initiated the request. The system allows only one VPN service to be active for a given user or profile. If a work profile, network protection feature or other VPN is already active, check whether it can be disabled under your organization's policy before trying to connect.

Some devices restrict apps running in the background. Check battery optimization, background activity limits and VPN status only if the app works in the foreground but disconnects after the screen locks, and you can reproduce the issue consistently. Don't enable every permission after a single failed attempt. If installation itself fails, check whether the system distinguishes an architecture mismatch, insufficient storage or an incompatible signature from an existing installation. Before uninstalling, make sure local groups and manually added entries can be restored.

Keep a first-launch record you can roll back

Record the package type, system architecture, configuration storage location and whether proxy mode was off at startup. Then start a known-good entry and check whether the core reports a parse error, missing resource or port conflict. The app can report an error while the core also logs one; start with the earliest specific error. If you only see a later connection timeout, you may have missed the real startup failure. Don't share full logs containing server details.

A port conflict doesn't automatically mean you need to change the port. First check whether another copy of the same client is already running. If you do need to change the local proxy port, update any browser, test command and system proxy setting that uses it. A listening core doesn't prove the remote server is reachable; verify these separately. If the window disappears immediately, see the startup crash troubleshooting checklist to narrow down the cause.

4. Importing Subscriptions: Add Groups, Update and Check Entries

Tell subscription URLs apart from individual share links

If your provider gives you a subscription URL, add it to a subscription group and then update the group. If you receive a single link starting with vmess:// or vless://, import it from the clipboard or use the QR code option. Subscription URLs are usually HTTPS, but the prefix alone doesn't tell you the format: a regular download page can also use HTTPS and will just return a webpage when pasted into the client. For details, see the difference between share links and subscription URLs.

A common subscription response is a plain-text list of links, or the same list encoded as Base64. Base64 is encoding, not encryption; treat the decoded content as sensitive configuration. Some providers offer other formats, which you may need to select in their settings for your client. Don't send an unfamiliar subscription to a third-party online converter or use a login page URL in place of a subscription URL. If the URL contains query parameters, copy it in full without deleting or changing anything.

Import workflow in v2rayN and Android clients

In v2rayN, open Subscription Group Settings and add a group. Enter a recognizable name under Remarks and the subscription URL under Optional address (url). Save it, then find the option to update the current subscription or that group. On the first update, update only the new group so you can check the result. Test a manual update before enabling automatic updates. Follow the interval units shown in the UI and your provider's guidance; there's no need to refresh repeatedly at very short intervals.

In v2rayNG, open Subscription Group Settings or the equivalent menu item, add a group, save it and return to the list to update. In v2flyNG, save the source first and then refresh its contents; menu names may vary by version. After the update, switch to the group you just added and check that its entries are there before selecting one to connect. Updating a group may not change the current selection or restart an active connection. For details on import options and formats, see the subscription import and format guide.

Troubleshoot the fetch, parse and connect stages separately

If fetching fails, check for an HTTP status or a DNS resolution error first. For an authentication failure, ask the provider to confirm your access and whether the URL has changed. For a timeout, distinguish the network path used to fetch the subscription from the path used by proxy traffic. Some desktop options let you fetch subscriptions through the current proxy; if that configuration can't connect yet, check whether the provider offers an update URL reachable directly from your current network. Don't hide the error type behind endless retries.

If fetching succeeds but the list is empty, check whether the response is a supported list or a login page, notice page or format for another client. Also check that you haven't selected the wrong group or enabled a filter. If the entries appear but won't connect, move on to the next stage: verify the selected entry, core support and connection logs. If an entry with the same name behaves differently after an update, its server address or transport settings may have changed. Compare the configuration, not just the name, and ask the provider whether anything was updated.

5. Proxy Modes: Check Whether Apps Use the Client

System proxy controls the entry point, not the outbound

In v2rayN, Set system proxy to auto-configure usually writes the local proxy address to system settings so apps that honor them can use it. Clear system proxy removes that setting; it doesn't stop the local listener. Don't change system proxy leaves the current value alone—it doesn't guarantee that no proxy was already configured. Before switching modes, check the system settings, especially on a device with a proxy configured by your organization. Don't mistake the original setting for something the client left behind.

Seeing a proxy address in system settings confirms only that the setting was written. Browsers may have their own proxy settings, command-line tools may use environment variables, and some apps ignore system settings and offer no proxy option. Check one app at a time. When configuring an app manually, choose HTTP or SOCKS to match the client's listener. Use the actual address and port: don't enter the remote server port as the local port or put a subscription URL in the proxy address field.

Compare requests using an explicit proxy

The commands below use curl to send requests to an example site. The first explicitly bypasses the proxy; the second explicitly uses the local HTTP proxy. The second assumes the client's HTTP listener is at 127.0.0.1:10809; replace it if the interface shows a different value. Run this comparison with TUN off. Otherwise, the first request could still be captured by the virtual network interface despite not using an application-level proxy. If your Windows command environment has a conflicting alias, call curl.exe explicitly.

curl --noproxy "*" --max-time 15 --head https://example.com/
curl --noproxy "" --proxy http://127.0.0.1:10809 --max-time 15 --head https://example.com/

If the second request can't connect to the local port, check that the core is running and verify the listen address and port. If you get a certificate error, keep the error and check the system clock, certificate trust and peer identity. An HTTP status proves that the request reached a point where a response could be returned, but not that the core chose a proxy outbound. To confirm the outbound, check the logs for the same time. If the target doesn't support HEAD, remove --head to make a regular request; don't mistake an unsupported method for a connection failure.

Mobile traffic routing and restoring settings after disconnecting

Android clients often use the system VPN service to receive app traffic. Before limiting coverage to selected apps, check whether the current mode includes only those apps or excludes them—the two behave oppositely. If a browser works but another app doesn't, first check whether that app is covered, then inspect the core's rules. A VPN indicator in the notification bar shows that traffic interception is active; it doesn't prove that any specific destination is reachable.

Restore your original network settings when testing is done. On desktop, undo the system proxy change made by the client using the method you chose, then quit the client. Check that the system proxy isn't still pointing to a local port that's no longer listening. If your original setup used an organization-required proxy, restore the settings provided by your administrator. On mobile, disconnect and use the same app to revisit the test target. Check whether always-on VPN or block connections without VPN is still enabled, and follow your organization's policy on managed devices.

By default, restrict the local proxy listener to the loopback address. Allowing LAN access is a separate setting that lets other devices connect to that port; it won't fix an app on your own device ignoring system proxy settings. Avoid widening the listening range just to troubleshoot, especially on public networks. Keep a separate way to check each of the three layers: the app, system proxy and core.

6. Routing: Rule Order, Domain Matching and the Default Outbound

Classify destinations before writing rules

Decide which destinations must connect directly, which may use a proxy and which should be blocked. A common approach is to put known local services and LAN ranges that should connect directly first, followed by specific domain exceptions, then define what happens to unmatched traffic. Many cores check rules in order and use the first match, so a broad rule near the top can hide a narrower one. This matters especially for block rules: their position determines whether a matching request can reach a later exception.

Outbound tags in your rules must match the tags defined in the active configuration. A UI label such as Direct doesn't guarantee the exported tag is named direct. Likewise, don't copy final → proxy from a static guide into JSON as if it were valid syntax. Default outbound fields and formats vary between cores. In a graphical client, check the rule group's default outbound. When reading core configuration, confirm how unmatched connections are handled.

Separate domain conditions from IP conditions

Use domain: to match a domain and its subdomains; use full: to match one exact domain. geosite: uses a domain collection, while geoip: uses an IP collection. These entries require the core to load the relevant resources and the collection to contain the name you're matching. For a stable private network, specifying its known address range is often easier to verify than relying on a whole collection. If domain matching works but an IP rule doesn't, check whether the current policy allows DNS resolution for matching.

IPIfNonMatch can resolve a domain for subsequent IP matching when no domain rule matches. It's not a global DNS switch for apps, and it can't reliably recover a domain from a request that already contains only an IP. The example below is a routing object for V2Ray-family cores, not a complete startup file. Before merging it into the routing field of a compatible configuration, confirm that direct and proxy are defined and replace the example domain and network range with verified test destinations.

{
  "domainStrategy": "IPIfNonMatch",
  "rules": [
    {
      "type": "field",
      "ip": ["127.0.0.0/8", "::1/128", "192.168.1.0/24"],
      "outboundTag": "direct"
    },
    {
      "type": "field",
      "domain": ["full:example.com"],
      "outboundTag": "proxy"
    }
  ]
}

Verify which rule matches, not just whether a page loads

Choose three test targets: a LAN resource that should connect directly, a test domain that should match a proxy rule, and an ordinary destination not covered by those rules. Record the inbound and actual outbound for each. If the page looks fine but the logged route is wrong, the rules still need work. Browsers may reuse existing connections, so start a new connection after changing rules. Images and APIs on a page may use different domains; don't infer the route for every subrequest from the main document's log.

If one destination behaves unexpectedly, check whether the request contains a domain or an IP, then see whether an earlier rule caught it. Change one rule with the narrowest possible scope and test again instead of temporarily expanding an entire address range. If adding a domain collection prevents the core from starting, restore the previous rules and check the collection name, resource location and load errors. For how DNS and outbounds work together in a full configuration, see the V2Ray JSON configuration structure guide.

Clients often generate the active configuration when starting the core. Direct edits to generated files may be overwritten on the next launch, so save rules in the graphical interface first and check the exported configuration. If you must use a custom configuration, save a working copy and verify separately that the core loads it and that the rules behave as expected. Before enabling new rules, make sure you can still access local management interfaces.

7. TUN Mode: Coverage, DNS and LAN Exceptions

Enable it only when you need broader traffic coverage

If an app honors system proxy settings, start with a system proxy or the app's own proxy setting. Use TUN when you need to capture IP traffic from apps that ignore application-level proxy settings. It uses a virtual network interface and system routes to send traffic to the core, so its impact is broader than changing a browser proxy. Whether it captures a given type of traffic still depends on system routing, permissions, the active core and app behavior. Turning it on won't automatically make every protocol, device discovery feature or LAN service work.

Get your existing setup working before enabling TUN: confirm the local listener works, the selected outbound can connect and basic routing behaves as expected. Record the current system proxy, network interfaces and DNS settings. Get permission first on managed devices where virtual adapters or routing changes are restricted. If the app asks for elevated permissions for this session, follow its instructions. Don't keep changing security settings to address startup failures, and don't enable TUN at startup while it's still failing.

Start with limited coverage, then test direct traffic and disconnect

In v2rayN's TUN settings, confirm that the selected core and platform support the feature. For the first test, turn off the system proxy used for comparison as directed by the guide or interface, and exit other traffic-interception tools so you don't change multiple paths at once. After enabling TUN, check that the client reports successful interface creation, then test an app that previously ignored system proxy settings. Start with a known test destination and confirm that the request appears in the logs.

Next, test resources that should connect directly, such as your own LAN admin page or a shared service. Excluding traffic from a system route isn't the same as using a direct outbound in the core: an excluded request never enters the virtual interface, while a direct outbound first passes through the core, which then connects to the destination. Apps that rely on broadcasts, multicast or a specific network adapter may need to stay on the original system path. Check the resource's actual network range first and use the exclusion method supported by your platform; don't copy someone else's list of private addresses.

Seeing an IP doesn't prove that DNS or the domain is working

With TUN enabled, an IP may be reachable while an app still can't resolve domain names. Compare the resolution result for the same domain before and after enabling TUN, then check whether the client changed its DNS interception settings. Some apps use their own encrypted DNS, so system lookup results may not reflect what the app sees. Before changing DNS, determine whether the query wasn't received, used a different resolver, or resolved successfully but failed to connect. Check interception boundaries in the first case; check routing or the outbound in the second.

If almost every connection times out after enabling TUN, check whether the client's own outbound connections are being sent back into the virtual interface. Implementations prevent loops through interface binding, route exclusions or other methods; don't blindly substitute settings from another platform. If only large requests stall while small ones work, then investigate MTU and path limits. Repeat the same test, record the original value and how to restore it, and don't blame MTU for one occasional slow request.

Finally, turn off TUN and retest system proxy status, the default network and LAN resources. If the interface is off but system routes haven't been restored, exit the app normally and use the operating system to inspect leftover interfaces and routes. Don't delete virtual interfaces you don't recognize. Android VPN services also capture traffic, but their menus and settings aren't interchangeable with desktop TUN. On mobile, check system authorization, app coverage and VPN status first.

8. Routine Maintenance: Updates, Backups and Layered Troubleshooting

Update one layer at a time

The client, core, rule resources and subscriptions can all be updated, but for different reasons. Client updates can change the UI and configuration migration; core updates may affect parameter compatibility; rule resource updates can change collection coverage; subscription updates directly change server entries. Don't update everything before testing, or you won't know which layer caused a problem. Verify the source and supported versions before updating, then rerun the same minimal test you used before the update.

At minimum, record the current client, selected core, listen ports, manual groups, routing order and TUN exceptions in your backup. Exported files may contain subscription URLs and account details. Store them somewhere access-controlled; don't post them in public groups or add them directly to shared projects. For entries your provider can issue again, you can keep recovery instructions without making another copy of the credentials. Before moving to another device, check that the backup format is supported; not every export can be restored across systems or versions.

Choose your first check based on the symptom

Where to start when something goes wrong
SymptomCheck firstThen
The interface closes immediately after launchSystem architecture, runtime warnings and directory permissionsCheck app error logs and why security software blocked it.
Subscription update failsGroup URL, authorization and the network path used for updatesDetermine whether the request failed or its response couldn't be parsed.
Only one app fails after connectingWhether the app honors system proxy settings, uses its own proxy, or falls within the capture scopeCheck whether the app's request reaches the client.
Only one destination failsThe destination's domain, address and rule orderCompare the actual outbound with logs from the same time.
No internet access after disconnectingSystem proxy, virtual interfaces and system VPN statusRestore the original settings and test a known destination.

In your troubleshooting notes, write down when the issue began, what changed and which apps are affected. 'It won't connect' isn't enough. If Wi-Fi fails but mobile data works, test the same app against the same destination on both networks and record whether you used the same group. Existing connections can retain old state after a network change, so reconnect before comparing. If some pages load but others don't, check the system clock and any certificate errors instead of assuming the server is down.

Keep logs limited to what you need to reproduce the issue

Note the time before reproducing the issue, temporarily enable the minimum log level needed to diagnose it, reproduce it once and then restore the normal level. If you need help, share a small set of adjacent log entries showing the earliest error, the test result and the settings that differ. Remove account identifiers, URL parameters and unrelated browsing information. A single timeout rarely distinguishes a local listener issue from a remote connection problem or a slow response. It becomes useful when paired with whether the request reached the client and which outbound was selected.

Verify your rollback, too. Restore the most recent change first, such as the previous rule group, instead of clearing all settings. After reloading, test the same three destinations to check the direct, proxy and default routes. Restoring only the client files won't reset TUN or the system proxy; traffic may still follow the new settings. After rolling back, confirm the app still works after a restart and note whether the change actually explained the failure.

Turn repeatable tasks into a checklist: confirm you can restore the configuration before updating; test one connection and one disconnect afterward; and periodically remove unused manual entries and expired groups. For installation and package selection, check the system requirements and FAQs on the downloads page rather than relying on what worked for an older device.

9. Next Steps: Reading Configurations, Controlled Tests and Handoffs

Read an exported configuration before deciding whether to write one by hand

Export a setup that you know works. In inbounds, find the entry point used by your test app and note its listen address, port and tag. In outbounds, check what each tag does. Then read routing to see how they connect. Finally, look at dns and log to understand which stages they affect. This order is easier to follow than memorizing parameters from the first line onward. Exports may contain account details, so keep your reading copy separate from shared examples.

Next, change one setting in the client interface and export the configuration again. Compare the two files to see which fields that change actually affected. A UI switch may adjust both an inbound and system settings, or it may not appear in the core file at all. For example, you can't tell whether the client changed the system proxy just by reading the core's routing section. Conversely, an inbound in the file doesn't mean the current app is using it.

Make configuration experiments repeatable

For each experiment, write down the expected result, a counterexample and when you'll stop. For example, to test exact domain matching, record the expected outbound for the target domain and for an ordinary domain that shouldn't match. After changing the rule, start a new connection, check the logs, then restore the rule and test again. If the result is unchanged, check whether an earlier condition captured the request or whether both paths already use the same outbound. Explaining a counterexample is more valuable than showing one successful visit.

When adding devices, standardize the intent of your rules, not the entire configuration file. A desktop may use a fixed listen port, while mobile relies on the system VPN's coverage. Sharing a subscription doesn't mean every device should use the same DNS or LAN exceptions. Keep a small set of tests tailored to each device type. On a new device, start with a minimal import and verify the basic route before adding only the rules you need. Don't bring over every advanced setting at once.

Keep records that others can understand and you can restore

For a handoff, explain in plain language which apps use the client, which LAN services must remain reachable, what the default outbound is and who updates the subscription. Attachments can include redacted configuration snippets, test destinations for comparison and rollback steps. Never include real account details in examples; use clearly fictional example domains. The next person should be able to understand the expected behavior, not just follow a screenshot to toggle settings.

Advanced configuration doesn't mean turning on every feature. Most everyday issues can be solved once you can tell whether a request never reached the client, took the wrong route or failed at the outbound. A small, clear rule set is more reliable than stacking unexplained switches. Periodically repeat the shortest path through installation, subscription update, connection and disconnect to make sure your notes still match the current interface. To revisit the basics, return to the Quick Start Guide.