Cross-Platform V2Ray
Setup Guide

Getting Started: System, Core, and Connection Details

Know the Difference Between a Client and a Core

v2rayN, v2rayNG, and v2flyNG are graphical clients for saving connection details, managing subscriptions, organizing routes, and starting a core. The core handles protocol parsing, remote connections, and traffic. Project V is an important starting point for this technology ecosystem; V2Fly and Xray are separate core development branches. Similar names do not mean their configuration fields, protocol extensions, or resource files are interchangeable. For desktop, start with v2rayN. On Android, v2rayNG, which uses Xray, is the usual starting point. Consider v2flyNG when you need compatibility with V2Fly configurations.

Before installing, identify your operating system, processor architecture, and preferred package type. The operating system narrows the options, but the architecture determines whether an app can run, while the package format affects shortcuts, permissions, and updates. A completed download does not mean the package is right for your device. Check processor details in your desktop system settings or Android device information. If you are unsure about the architecture, consult the device manufacturer's specifications instead of trying packages at random.

Use a Configuration Source You Can Verify

The client does not include working servers. You need an authorized subscription URL, a single-node share link, or a configuration file compatible with your chosen core. Each has a different import path: a subscription is a remote address that can be fetched again, a share link usually describes one connection, and a full configuration may also define listening ports, outbound connections, and routing. Confirm the format and supported clients with the provider before choosing an import method. This helps avoid treating a webpage URL as a subscription or pasting a full JSON configuration where a node link belongs.

Connection details should specify at least the server address, port, protocol, and required identity information. For TLS or another security layer, also check the server name, transport type, and related parameters. Required fields vary by protocol; do not add arbitrary values just to dismiss a warning. Keep device time synchronized automatically, since a significant clock difference can affect certificate validation. The network should also be able to reach your local gateway and ordinary websites first; otherwise, a failed remote connection cannot be attributed to the client alone.

Start with a Minimal Test Setup

For your first test, run only one proxy client and close other VPNs, proxy apps, and browser extensions that might route traffic. Note your current system proxy settings. Leave complex rules, custom DNS, and TUN off for now. First confirm that one node works with one traffic-routing method, then add settings gradually. Change one thing at a time and save a screenshot or note of the previous settings. Rolling back to the last known state makes problems much easier to diagnose than enabling everything at once.

Keep basic troubleshooting details on hand: client name, system architecture, active core, traffic-routing mode, and the steps that triggered the error. Describe the environment; do not share your full configuration. When moving to another device, import the required details and test them there before cleaning up the old device. Keep these outcomes separate: successful installation means the app runs, a successful subscription update means it retrieved configuration, and proxied app traffic means requests are actually taking the intended route.

Windows: Install v2rayN and Configure Proxy Settings

Choose the Desktop or Classic WPF Version

Choose v2rayN from the Windows client downloads. The desktop version uses a cross-platform interface, while the classic WPF version retains the traditional Windows interface. Both manage connections, but their layouts, runtime requirements, and some menu locations may differ. The desktop version is a good starting point for new users; if you already use the classic interface, choose WPF to suit your workflow. Do not run both versions at once to compare connections, as they may conflict over local listening ports, system proxy settings, and background processes.

Before running the installer, check that your system meets the package requirements. Choose an installation location in the setup wizard. If the app reports a missing runtime on first launch, install the specified component and restart the client instead of downloading a similarly named program. Make sure your user configuration directory is writable. A restricted install location or switching between user accounts can prevent settings from being saved. If security software blocks the app, review the file path and reason in its alert; do not disable system protection wholesale.

Import a Subscription and Select an Active Server

Open the subscription group settings, give the source a recognizable name, and paste the full subscription URL into the address field. Save it, then update the subscription. When the update finishes, confirm that servers actually appear in the list rather than relying on a notification disappearing. For a single-node share link, use the clipboard import option; it will not become a subscription that updates automatically. For the first test, select a server with complete parameters, set it as active, and check that the current core supports its configuration.

If an update fails, first check whether the client received configuration content. A redirect to a login page, a permissions error, and an unsupported format are different from a node connection timeout. If the subscription source cannot be reached directly on your current network, try updating through an existing working connection. Without one, repeatedly changing the update method will not create a path to the source. See the subscription update and parsing error checklist for a step-by-step review.

Start with System Proxy; Consider TUN Later

For a first connection, enable “Set system proxy automatically.” Once the client core is running, open an app that respects the system proxy. In Windows, the system proxy typically points to a local loopback address and a client listening port, not the remote server. Browser access confirms only that this route works; it does not mean every desktop app uses the system proxy. If an app has its own proxy settings, explicitly choose the system setting or enter the relevant local address. Avoid conflicting settings at the system and app levels.

If you need to route apps that ignore the system proxy, check whether your version of v2rayN offers a working TUN option. Setup may require elevated permissions or a virtual network interface; read the client's authorization prompts. After enabling TUN, check that the network interface, routes, and DNS are all configured rather than relying on the toggle alone. Remote desktop, work VPNs, and virtual machine networking may be affected by route changes. Keep local access available while testing, and turn TUN off to restore connectivity if ordinary network access is interrupted.

Quit, Update, and Clear Stale Proxy Settings

When finished, clear the system proxy in the client before quitting normally from its menu. If the process crashes, Windows may still point to a stopped local port, preventing apps that use the system proxy from connecting. Check Windows proxy settings and restore the previous value. Back up your configuration before updating, and exit the old process so you can roll back if needed. If the app does not start at login, check that it uses the same account, that its shortcut is valid, and that security policies are not blocking it. Avoid creating duplicate startup tasks as a workaround.

macOS: Chip Selection, Permissions, and Network Services

Choose the Package for Your Chip

Check your chip in About This Mac. Apple Silicon uses arm64; Intel uses x64. Choose v2rayN from the macOS downloads. Do not confuse processor architecture with the macOS version: the same OS version can run on different chips. Open the disk image and follow its instructions to move the app into Applications, then launch it from there. Running the app from a mounted image long-term may cause unexpected update, permission, or shortcut behavior.

If macOS displays a security warning on first launch, check the download source, app name, and the specific reason given, then use Privacy & Security settings to proceed. Security restrictions, organization-managed device policies, and a damaged download require different solutions; do not use terminal commands to remove every restriction. A managed work device may not allow network interfaces or proxy changes. Confirm the device's authorization requirements rather than repeatedly reinstalling the client.

Import a Subscription and Test the Connection

Create a subscription group in v2rayN, paste the full URL, save it, and start an update. For your first test, select a server as active and check that its protocol, server name, and transport type match the provider's instructions. Menus may vary between cross-platform client versions. If you cannot find an option by name, look for functions such as subscription groups, system proxy, or routing settings. Do not copy Windows configuration paths or shortcuts directly to macOS. Test a basic connection before restoring other custom settings.

After enabling the system proxy, open Network settings and check whether the active network service has the proxy address set. Wi-Fi, Ethernet, and other services may store proxy options separately, so check again when you switch networks. Automatic proxy configuration scripts and manual HTTP, HTTPS, or SOCKS proxies use different fields. If you previously used another tool, note its settings first. Keeping a script URL while adding a manual proxy can send apps through different routes.

TUN, Permissions, and Recovery After Sleep

TUN availability on macOS depends on the client build, core integration, and system permissions. If the feature is available, follow the prompts to configure any helper component or permissions, then check the logs for interface creation. Do not assume every desktop version uses the same permission flow. After enabling TUN, test ordinary websites, destinations that require a proxy, and local network services separately. If websites work but a printer or shared folder does not, check whether direct routes cover the local subnet.

After sleep, wake, or switching from Wi-Fi to Ethernet, the old connection may be invalid even though local proxy settings remain. First confirm that the network is back, then reconnect to the active server. If the TUN interface has not recovered, disable and re-enable it, and check for duplicate interfaces or permission errors. Do not start by deleting all subscriptions. Browsers, remote sessions, and network services each maintain their own state. Restarting the app, the client connection, and the relevant traffic-routing mode in sequence helps pinpoint what stopped working.

Keep Migratable Data Before Updating

Before upgrading, stop the connection normally and save subscription groups, essential local nodes, and custom rules. Reinstalling the app does not necessarily delete user configuration, and deleting the app does not necessarily clear the system proxy. After uninstalling or disabling it, check that the proxy has been restored for the active network service. When moving to another Mac, prioritize subscriptions and readable rules, then reconfigure local ports, startup behavior, and system permissions. These settings depend on the device; copying the old machine's entire runtime directory over the new one is not recommended.

Linux: Packages, Desktop Proxies, and Permission Boundaries

Match the Package to Your Distribution

To use the v2rayN graphical client on Linux, first check whether your distribution uses deb or rpm packages, then confirm your processor architecture. Debian-based distributions and derivatives generally use deb; distributions in the RPM package ecosystem use rpm. x64 and arm64 packages are not interchangeable. The Linux client downloads list both package types. A matching package format does not guarantee compatibility with older systems; read the installer's dependency requirements instead of forcing an installation by ignoring them.

Use your distribution's software installer to open the downloaded package, so the system package manager handles dependencies, installation paths, and uninstall records. If the installer reports missing graphical libraries, first check the supported system range, then install them through your distribution's normal channels. Do not run the entire client with elevated privileges just to make its interface appear. That changes configuration file ownership and expands access to subscriptions and local files. Settings saved as a regular user may be in a different location from those created when running as root.

Desktop Sessions and App Proxies Work Differently

After importing a subscription in the graphical interface, updating the list, and selecting an active server, first check that the client's local listener works. Linux desktop environments vary in their support for system proxy settings: some apps read desktop settings, others use environment variables, and some only honor their own configuration. So “system proxy enabled” means the client attempted to write to a desktop proxy interface; it does not mean terminals, software installers, and all graphical apps will use the same route.

For apps that need individual configuration, first find the address, port, and supported type of the client's local HTTP or SOCKS entry, then enter them in the app's settings. Environment variables generally affect processes launched afterward; already-running terminals and apps may not pick up changes. Do not enter a remote server address in a local proxy field or guess the protocol from a port number. If the client labels an entry as a mixed listener, follow that label. For separate listeners, select the matching HTTP or SOCKS protocol.

# Check the current desktop session and core architecture
printf '%s\n' "$XDG_CURRENT_DESKTOP"
uname -m

# Show TCP ports currently listening on this machine
ss -ltn

TUN Permissions and DNS Troubleshooting

Creating a TUN interface and changing routes usually require extra permissions, but the authorization method depends on the client build and distribution. Follow the current client's process and check for specific permission or interface errors if it fails. Do not run copied commands with elevated privileges on files you have not verified. Firewalls, other VPNs, container networks, and policy routing can all affect traffic forwarding. Start with a simple network setup, then restore these components one at a time and note which change affects the connection.

DNS may also be managed by the desktop network service, a local resolver, or another network tool. If TUN starts but domain lookups fail, compare access by domain with connections to a known destination, then check the logs for DNS requests and upstream reachability. Do not immediately overwrite system resolver files: a service may generate them automatically, and manual changes can be lost or disrupt other network tools. Check who controls DNS across the client settings, active network service, and any conflicting apps.

Tray Icons, Startup, and Saved Settings

Some desktop environments do not show a traditional tray icon by default. If the icon disappears when you close the window, the process may still be running. Check the process and listening ports before restarting to avoid multiple instances competing for a port. Start the client after the current user's desktop session is ready; launching too early may prevent it from accessing the proxy interface. Quit the client and back up essential settings before updating, then check file ownership and write permissions. If settings save only when running with elevated privileges, fix ownership of the configuration directory rather than using elevated access for everyday use.

Android: VPN Authorization, Background Access, and Per-App Proxying

Choose Between v2rayNG and v2flyNG

On Android, start with v2rayNG, which uses the Xray core. Consider v2flyNG when you need compatibility with V2Fly. Similar names do not mean the clients support all the same protocol extensions. Choose a package for your architecture from the Android downloads. Most newer devices use arm64; if you are unsure or have an unusual device, check the manufacturer's information and choose a universal build if needed. A universal build covers more architectures; it does not provide different servers or connection capabilities.

When installing, allow installation from the current file source only if needed, and only for that source. You can restore the previous permission setting afterward. To update an existing client, the app identity and signature must be compatible. If Android says the app cannot be installed over the existing one, first confirm that you downloaded the same client; do not uninstall it immediately. Uninstalling may remove local nodes, custom settings, and per-app lists. If you do need to reinstall, save essential data using the client's available export option first.

Import Connection Details and Make Your First VPN Connection

In the client subscription settings, add a group name and full URL, save it, and update. For a single node, use the appropriate clipboard or QR code import option. Confirm that the server appears in the list, then select it as active. When you connect, Android displays a VPN permission prompt. VpnService requires this system permission to create a local virtual interface. Confirm that the app name is correct before granting access. Denying permission, another window interrupting the prompt, or an existing VPN using the service can prevent the client from routing device traffic.

Android generally allows only one VPN service per user profile to be active at a time. Another VPN or filtering app with local VPN features may replace the current connection. Close competing services first, then check the system VPN indicator and client logs. That indicator confirms only that a virtual interface was created; it does not prove the remote server is reachable. Test the destination in an app and check the logs for its request. If the network works but a particular app does not, check the per-app rules instead of requesting VPN permission again.

Background Disconnects and Network Switching

Power-saving features may restrict background network access or stop the client process. If the connection drops after the screen has been locked for a while but returns when you reopen the app, check battery optimization, background activity limits, and the manufacturer's auto-start settings. Names vary by device; adjust the client rather than changing settings for every app. A persistent notification may keep a foreground service running. Whether it can be hidden and what that affects depends on the Android version; do not disable permissions or services that keep the connection alive just to clear a notification.

Switching between Wi-Fi and mobile data changes the underlying network, so the existing connection may need to be re-established. Confirm that the new network works, then check whether the client has rebuilt the tunnel. Android's Always-on VPN and blocking connections without a VPN options affect what happens when the connection drops; understand the consequences before enabling them. If all apps lose access when the client is stopped, check these system settings to distinguish an intentional block from a fault. Do not assume the subscription has failed.

Per-App Rules and Switching Clients

Per-app proxy settings typically offer opposite modes: only selected apps use the VPN, or selected apps bypass it. Check which mode is active before selecting apps; if the browser is excluded, a working node will not route its traffic. Work profiles, app clones, and separate user profiles may have distinct app identities that are not covered by the original list. Reconnect as required by the client to apply the updated app selection. See VPN permissions, battery optimization, and per-app proxying for more system details.

When switching from v2rayNG to v2flyNG, stop the old client's VPN first. Import the subscription into the new client and check protocol support. Do not overwrite the app's data by copying its entire internal configuration. Per-app lists, notification permissions, and battery optimization settings are local app settings and need to be checked again. Confirm a basic connection before restoring complex rules. If only one protocol fails, compare core support and the provider's parameters instead of changing every node at once.

Subscriptions and Migration: Formats, Groups, and Data Protection

Subscription Updates vs. Node Imports

A subscription update fetches content from a URL and parses it into server entries. It requires three things: the URL is reachable, the response contains configuration, and the current client recognizes its format. Opening the same domain in a browser only confirms that some network paths work; the subscription endpoint may require different permissions or return an error page. Conversely, a successful import does not mean every node can connect. The client may not verify the status of each remote server while parsing the configuration.

A single-node share link usually saves the parameters as they are now. It will not sync automatically if the provider later changes the address or port. A full custom configuration has a wider scope and may define its own inbound connections, outbound connections, routing, and DNS, bypassing some graphical client settings. Before importing, make sure the import option matches the data type. Do not split a full configuration into similar-looking fields in a node editor, or treat a bookmarked subscription management page as the subscription URL itself.

https://subscription.example.net/client?token=xxxx

Groups, Update Overwrites, and Local Changes

Use separate groups for different subscription sources, with short names that identify their source and purpose. Update one group first and confirm the response is valid before running a bulk update. Node aliases are display names, not necessarily stable identifiers. A provider may rename nodes, merge them, or change their order, making the previous active selection invalid. If a connection fails after an update, check that the active server still exists and that its actual parameters have not changed. Do not assume an old alias still refers to the same connection.

Entries managed by a subscription may be overwritten the next time it updates. If you need to edit a node, check whether the client can copy it to a standalone local entry, and note that it will no longer follow the source automatically. Keep custom rules, subscription nodes, and temporary test nodes separate to avoid deleting manual settings when cleaning up a group. Limit bulk filtering and speed tests to the intended scope. Testing every source at once creates extra requests and can skew results due to local bandwidth and connection limits.

When Subscription Conversion Helps—and When It Doesn't

A format mismatch cannot always be fixed by conversion. A converter can rearrange fields or generate another client format, but it cannot give the target core protocol features it does not support or reliably fill in missing authentication details. If conversion is necessary, confirm the input and output formats and the target core's capabilities first. Giving a subscription with access credentials to an unfamiliar online service may expose that data to the service. Prefer a compatible format from the source provider to limit unnecessary data sharing.

If an update reports an encoding or parsing error, save a short error message and check whether the URL contains extra spaces, line breaks, or characters added by a messaging app. Do not rewrite query parameters in a browser or share the full response publicly. If only one group fails while others work, focus on that source's permissions, response format, and protocol compatibility. For managing multiple sources, see subscription groups and server filtering in practice.

Cross-Platform Migration Is Not Automatic Sync

Moving between platforms usually means reimporting subscriptions, exporting essential local connections, and bringing over compatible rules. It does not mean the clients have built-in cloud sync. Desktop listener addresses, window settings, permission components, and system proxy state should not be copied as-is to Android. Quit the client normally before backing up to avoid copying a file that is still being written. After restoring data, test a basic node before restoring routes one at a time. When retiring an old device, remove data you no longer need. If you suspect a subscription has leaked, revoke or replace its credentials with the provider; deleting the local record does not invalidate the old URL.

Proxy and Routing: Entry Points, Outbound Connections, and DNS

First Check Whether Traffic Reaches the Core

A request passes through several stages: an app generates it, a local entry receives it, routing selects an outbound connection, and the core connects to the remote server. System proxy and TUN determine how traffic reaches the client; routing rules determine what happens next. Changing remote routing will not affect an app that never uses the system proxy. Check the logs for a request from the app first, then see whether it was routed directly or through a proxy. This is more useful than switching every mode repeatedly.

A system proxy works for apps that follow system settings. A local HTTP or SOCKS entry can also serve apps with their own proxy settings. Keep the listener on a loopback address so only the local machine can access it. Exposing it to the network could let other devices connect and would require authentication and firewall rules; it is not a routine fix for connection problems. No port number is inherently faster. What matters is that the port is available, the protocol matches, and the system and app settings match the actual listener.

Rule Order and Outbound Tags

The core usually checks rules in order, and the first match determines how traffic is handled. A broad rule near the top may prevent more specific rules below it from taking effect. Outbounds such as direct, proxy, or block must actually exist in the configuration, and referenced tags must match exactly. Built-in presets such as “bypass mainland China” depend on the current rule implementation and resource files; they are not a guarantee for every situation. Verify behavior for local networks, work networks, and specific domains in your environment.

This Xray routing snippet illustrates the structure; it is not a standalone configuration. It assumes an outbound tagged direct already exists and that the referenced rule resources are available. Private-address traffic goes direct first; other traffic continues through subsequent rules and the default outbound. A graphical client may regenerate its configuration on startup, so edits to generated files may not persist. Use the client's supported rule editor where possible.

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

Understand DNS and Routing Together

DNS resolves domain names to addresses; routing decides which outbound handles the request, and the two can affect each other. If an app resolves names through the system first, the core may see only the destination address. If a request includes the domain name, the core may be able to apply domain-based rules directly. Entry type, sniffing settings, and resolution policy all affect what information is visible, so the same destination may take different routes in different apps. Adding a domain rule alone does not guarantee that every request will match it; check the entry type and logs.

If domain lookups fail while other connections work, check which resolver is actually in use, whether the upstream is reachable, and whether DNS requests are routed through a working outbound. Do not change multiple resolvers, enable sniffing, and rewrite all rules at once. Change one setting at a time and see whether the error changes from a resolution failure to a connection timeout or clears. After enabling TUN, check whether DNS is being handled as intended by the client; the system's existing resolver settings may not match the new route. Work networks often require their internal domains to use the right resolver and a direct route.

Verify TUN and Real-World Reachability

TUN covers a wider range of traffic, but it still depends on system permissions, route exclusions, DNS, and core capabilities. It does not guarantee that every UDP use case will work. Test destinations that require a proxy, local network resources that should connect directly, and everyday apps separately, and check for routing loops. A low latency result in the server list reflects one test path, not actual download speed or app performance. See Ping, real connection latency, and speed test results compared to avoid changing your entire network setup based on one number.

Common Setup Questions: Trace Symptoms to Their Source

Gather Evidence in a Consistent Order

When a connection fails, identify the stage: the app will not open, a subscription will not update, the core will not start, or an app cannot connect. Each calls for a different fix. First confirm ordinary network access, then check the active server and traffic-routing mode, and look for the first error in the logs. Do not capture only the final line after repeated retries; it may be a knock-on effect of an earlier failure. Note the time, destination type, and settings changed so you can correlate the request with the logs.

If the app starts but the core exits, check configuration syntax, field compatibility, local port conflicts, and missing resources. If the core runs but there are no requests from the app, check the system proxy, the app's own settings, and any per-app list. If a request appears but times out remotely, compare the server address, port, network route, and server status. For a complete sequence, see how to troubleshoot node timeouts and connection failures. Narrow down the issue before changing anything.

Handle Certificate, Port, and Permission Errors Separately

For certificate errors, check the device time, server name, and security-layer requirements in the configuration, then confirm the subscription is up to date. Do not permanently bypass certificate validation to hide a mismatch; that changes the connection's security boundaries. Resolve port conflicts locally: close other clients or duplicate processes, identify the listener, and change the local port if necessary, updating any apps that use it. Permission errors usually involve the configuration directory, interface creation, or system policy. Find the specific cause instead of always running the client with elevated privileges.

Create a Minimal Reproduction and Keep a Rollback Path

To isolate a complex issue, create a minimal setup with one known configuration source, one active node, one traffic-routing method, and one test app. Temporarily disable custom rules, but back them up first. If the minimal setup works, restore DNS, rules, and other app settings one at a time to find what triggers the problem. If behavior changes after an update, check configuration migration, core selection, and rule resources. Keep the old configuration and note what changed so you can roll back instead of repeatedly overwriting the installation.

When asking for help, share the operating system, client, core, traffic-routing mode, and a brief error summary with sensitive details redacted. Do not post full subscription URLs, node identity details, or your entire configuration directory, and do not treat one test result as universal. After restoring the connection, keep a brief note of the fix and undo any temporary changes to listener exposure, permissions, or security settings. New users can return to the Quick Start guide to rebuild the connection step by step. To switch platforms or package types, choose the relevant option on the client downloads page.