v2rayN Setup for Every Platform

Before You Begin: Check Your Configuration and Network

Understand the Client, Core, and Server Configuration

v2rayN is a graphical client for managing configurations. It stores server details, generates runtime settings, and uses an available core to handle traffic. Xray and V2Fly are different core implementations in the proxy ecosystem, with some differences in protocols and features. Installing a client only gives you a local tool; it does not provide a remote server. Before you start, get a subscription link or complete connection details you’re authorized to use, and confirm which clients, transport methods, and authentication details the provider supports.

A subscription link is a configuration source, not a server address. Manual setup requires entering the address, port, protocol credentials, and transport settings individually. First identify whether your details are a subscription, a single share link, or a core configuration file, then use the appropriate import method. Don’t paste a complete link into the server address field, or treat a webpage with setup instructions as subscription data. If details are missing, ask the provider rather than guessing; filling in unknown fields usually makes troubleshooting harder.

Establish a Recoverable Baseline

Close other proxies and virtual network tools that are taking over traffic, and leave one client running for testing. Open a regular webpage to confirm your internet connection works. Turn on automatic date and time in system settings and check the time zone. An incorrect system clock can interfere with certificate validation and protocols that check timestamps. On a managed computer, check your organization’s proxy, certificate, and network extension policies before changing existing settings.

Record your existing system proxy, manual DNS, and network interface settings. Before sharing screenshots, hide account details and links. Change one type of setting at a time: test the server first, enable the system proxy next, and only then consider TUN. That way, you can roll back to the last working state if something fails. For your first connection, avoid changing DNS, switching cores, and importing complex rules all at once. When several variables change together, it’s hard to tell which one made the difference—even if the connection starts working again.

Choose what to route, then test

The system proxy only affects apps that respect the system proxy settings. Browsers usually do, but command-line tools, games, and apps with their own networking stack may not. TUN routes more traffic through a virtual network interface, but it also needs the right permissions, routes, and DNS settings. Start by testing the system proxy. Set up TUN only if your target apps don’t use the system proxy or you need device-wide routing.

During testing, distinguish between three states: the configuration is saved, the core is running, and a webpage is reachable through the expected route. Seeing a server in the window doesn’t mean authentication succeeded; a running indicator in the tray doesn’t mean your browser is sending traffic through it. Test a site that normally works and a destination that should use a specific outbound, then check regular access, proxy access, and direct-routing rules in turn. Use the logs to interpret the results rather than relying on an icon or a single speed test.

Find downloads on the client downloads page. Open the section for your platform, then check the architecture and package type. Menu layouts vary, so if you can’t find an exact match, look in the areas for subscriptions, settings, or system proxy. To get a basic connection working first, follow the quick start guide, then return for the backup and troubleshooting sections.

macOS: Chip Selection, Installation, and Network Permissions

Choose the Right Installer for Apple Silicon or Intel

Open the Apple menu and select “About This Mac,” then check the “Chip” or “Processor” field. If it shows an Apple chip, choose the Apple Silicon installer in the macOS downloads section. If it shows Intel, choose the Intel installer. They’re built for different processor architectures, so don’t choose based on the computer’s appearance. Having a translation layer installed doesn’t mean you should use the other architecture; a native match makes it easier to verify that the core, helper components, and permissions are working correctly.

Open the downloaded disk image, drag v2rayN into Applications, and launch it from there. Don’t keep running it from the disk image; doing so can interfere with updates, saved settings, and helper component detection. If macOS says the app can’t be opened, first confirm that it came from the designated download page, matches your architecture, and finished downloading. Then check the specific message under “System Settings → Privacy & Security.” Don’t disable system-wide security just to launch one app.

Import Your Configuration and Check the System Proxy

After opening the app, go to subscription group management and add a clearly named group. Paste the complete subscription link into the address field, save it, and update the subscription. If the update menu offers options to use or bypass the proxy and you don’t have a working connection yet, try updating without the proxy first. If the subscription address requires a proxy, you’ll need a separate working connection. Once the update succeeds, make sure the group contains selectable servers, then set your chosen server as active.

Start the core, then choose “Set system proxy” from the system proxy menu. This client action is not the same as a browser’s proxy auto-configuration script mode. In “System Settings → Network,” open the network service you’re currently using and check the proxy host and port under its details. They should match the client’s local listener. Wi-Fi and Ethernet are separate services, so check the active service again after switching networks.

Test with a browser first, then check other apps. Browser extensions, app-specific proxy settings, and environment variables in developer tools can override system settings. If the browser works but another app connects directly, check whether it uses the system proxy before switching servers. When you’re done, choose “Clear system proxy.” “Do not change system proxy” usually means the client will stop modifying the settings; it does not clear them.

TUN and Recovery After Sleep

Only consider TUN after confirming the system proxy works. Depending on the installation and runtime environment, TUN may require a helper service, network extension, or administrator approval. Grant the necessary permissions as prompted by the client and macOS, then check that the core created a virtual interface successfully. If an authorization dialog keeps reappearing, don’t keep clicking retry. Close extra instances, check the logs for permission, service installation, or interface creation errors, and follow the relevant recovery steps. Ask your administrator about restrictions on managed work devices.

If the connection stops working after closing the lid, waking the Mac, or switching from Wi-Fi to Ethernet, turn off TUN first and confirm that regular internet access returns. Then restart the core and enable traffic routing again. If the client exits but leaves the system proxy pointing to a local address, webpages may stop loading. Restart the client to clear the proxy or restore the recorded settings for the active network service. Don’t leave a proxy entry pointing to an unmonitored port when the client is closed.

Back up subscription groups and custom rules before upgrading, then quit the old instance before replacing the app. If macOS says the app is still in use, check the menu bar and background processes. Don’t import settings while old and new instances are running together. After replacing the app, test the regular proxy first, then TUN and automatic startup. This helps separate configuration compatibility or permission issues from installation problems instead of blaming every connection failure on the installer.

Windows: Desktop Edition, WPF, and System Proxy

Choose an Edition for Your Workflow and Compatibility Needs

The Windows downloads section offers a desktop edition and the classic WPF edition of v2rayN. The desktop edition uses a newer cross-platform interface, while WPF retains the classic workflow. For a new installation, consider starting with the desktop edition. If you already have a well-established setup, back it up before deciding whether to migrate. The editions may use different interfaces and configuration locations, so don’t assume they’ll share all data after installation. Don’t run both as if they were independent proxies, either.

Before installing, check that your operating system and processor architecture match the download card, and make sure your user account can write to its required folders. Follow the installer instructions. If you’re using a portable package that needs extracting, extract all of it before launching; don’t run the app from an archive preview window. If a runtime dependency is missing, check the required dependencies and supported Windows versions. Don’t try to fix it by copying an unknown DLL into the program folder.

Import a Subscription and Check the Local Port

Launch v2rayN, create a subscription group, enter the subscription address, save it, and update. A successful fetch only confirms that the configuration source is reachable; you still need to select an active server and start the core. For a manually imported share link, check that the protocol, address, port, and transport fields are complete, then confirm it’s saved in the intended group. If you have older configurations, test with a clearly named group first to avoid selecting the wrong entry from similarly named default and subscription groups.

Check the local listening address and the HTTP or mixed proxy port in settings. The port must match an inbound listener enabled in the client; don’t copy a commonly used number from another guide. If the listener is only for local use, keep it bound to the loopback address. Enabling LAN access requires additional attention to authentication, firewall rules, and who can connect. If a port is already in use, identify the process using it before stopping an old instance or choosing another port. Update any apps where you manually entered the old port.

After enabling automatic setup in the system proxy menu, open “Settings → Network & Internet → Proxy” and make sure the manual proxy matches the client. Temporarily disable any separate proxy extension in your browser before testing. Some apps cache network settings and may need a restart. Seeing a local proxy address in Windows settings doesn’t prove the core is listening; also check the client logs for startup or port-binding errors.

TUN, Permissions, and Background Instances

Before enabling TUN, read the client’s prompts about services and administrator permissions. Some setups require elevated privileges or a helper service, but that doesn’t mean you should run the client as administrator for ordinary system proxy testing. Grant only the permissions required, then check that the virtual adapter was created and routing and DNS takeover completed. If security software blocks a network component, review the alert and file location, then follow your organization’s policy. Don’t troubleshoot by disabling all security protection.

Multiple tray instances, startup items, and old services are common sources of confusion on Windows. Closing the main window may not quit the app; use the tray menu’s exit command. If the proxy setting changes again after a reboot, check startup apps and other network tools to find what takes over the system proxy at sign-in. When migrating, quit the old client and stop its traffic takeover before launching the new one. Otherwise, both instances may keep changing system settings, making the connection seem unreliable.

If your browser works but a terminal app doesn’t, check whether it uses the system proxy or has its own proxy environment variables. Enter an address manually only after confirming the required protocol and listener type. If no webpages load, check the local port, core startup, and system proxy one at a time. For more browser troubleshooting, see the connected but can’t browse checklist. You don’t need to reinstall the entire client as a first step.

Linux: Package Formats, Desktop Proxy, and TUN

Check Your Distribution and Processor Architecture

Choose a Linux package based on two things: your distribution’s package format and your device’s processor architecture. Debian and Ubuntu systems typically use deb packages; Fedora systems typically use rpm, but follow your distribution’s package management guidance. Most personal computers use x64, while some development boards and desktop devices use arm64. In the Linux downloads section, check the package format first, then the architecture. Package format and processor type are not the same thing.

Run these two read-only commands in a terminal to check your system. The output x86_64 usually corresponds to x64, while aarch64 usually corresponds to arm64. Distribution details identify the package management system. These commands only inspect your device; they don’t install or change the client. If your device uses another architecture, don’t force an incompatible package to install. Check whether the download page has an option for your environment.

uname -m
cat /etc/os-release

Open the downloaded package with your distribution’s software installer, review the dependencies and installation prompts, and complete the installation. If dependencies are missing, let the system package manager resolve them; don’t copy library files between distributions. Launch v2rayN from the application menu and confirm that a regular user can save settings. If you previously ran the client with elevated privileges, its configuration directory may have ownership issues. Check the specific directory and permissions before fixing them; don’t recursively change permissions across your entire home folder.

Import Configurations and Understand Desktop Proxy Differences

Save the link in a subscription group, update it, select a server, and start the core. First check that the local listener is working. Linux desktop environments don’t handle system proxy settings uniformly: some clients can update the desktop proxy settings, while others require you to enter them in the system network panel. GNOME, KDE, and individual apps may also read settings differently. Even if the client says the proxy is set, verify the actual address and port in your current desktop network settings.

Command-line programs usually don’t use the proxy just because the desktop proxy is enabled. They may use environment variables, command-line options, or their own configuration files. Check the target program’s proxy documentation and choose settings that match the client’s listener type. HTTP and SOCKS proxies don’t share all syntax just because both use a proxy address, and remote DNS behavior varies by program. Don’t add proxy variables to several startup files at once; it’ll be harder to find where an outdated port is coming from.

Least Privilege and Virtual Interface Checks

TUN requires a virtual network interface and suitable network permissions; being able to launch the graphical app doesn’t guarantee either is available. Set up a service or grant permissions using a method supported by the client. Avoid running the entire desktop app with elevated privileges as a long-term workaround. If the logs report a missing interface, a permission error, or a failed route update, first check whether the system provides a TUN device and whether containers or restricted sessions allow access. Then determine whether the issue is permissions or core startup.

Use the read-only commands below to inspect addresses and routes. When comparing the results before and after enabling TUN, look for a new interface and where the default route points. The interface name alone doesn’t tell you whether the connection works. Other virtual networking tools may compete over route priority. Keep only one traffic takeover active while testing: confirm the regular proxy works, then enable TUN. After turning TUN off, make sure the system routes have been restored rather than just checking the client switch.

ip address show
ip route show

If direct connections work on Linux but the proxy doesn’t, check the local listener and core logs first. If only domain names fail, investigate the DNS path next. System DNS may be managed by the network service, a resolver, or connection settings; don’t overwrite resolver files and hope for the best. Keep a backup of user settings during upgrades, replace the app through your package manager, and check desktop proxy settings, background services, and autostart one by one. Make sure no old service still points to a program path that has changed.

Android: Configure v2rayNG and v2flyNG

Choose a Client, Then Match the Installer Architecture

For Android, v2rayNG with the Xray core is the recommended choice. Consider v2flyNG if you need compatibility with the V2Fly core. Don’t let both clients take over the network at the same time; first check which protocols and core features your connection details require. Choose the appropriate option from the Android downloads section. Most newer phones use arm64, but check the system architecture to be sure. If you’re unsure, consider the universal build rather than relying on the processor’s marketing name.

When you open the installer, Android may ask you to allow app installs from your current browser or file manager. Grant permission only to the source you’re using, and revoke it afterward if you prefer. If installation fails, check the Android version requirement, whether the package finished downloading, whether its architecture matches, and whether an app with the same name but a different signature is already installed. Don’t immediately uninstall an older app if an upgrade fails; back up your settings first, since uninstalling usually removes the app’s private data.

Subscriptions, Share Links, and Active Configurations

Open subscription settings or group management, add a subscription name and full URL, save it, then return to the main screen and update. Menu names may vary, but the sequence is the same: save the source, fetch its contents, then select an active configuration. Import a single share link using the appropriate clipboard option. Before importing a QR code, check that it comes from a trusted source. Don’t upload a QR code containing credentials to a public decoding service.

After importing, open the configuration details and check the protocol, remote address, port, and transport security settings. Subscription entries are usually managed by the provider, so local edits may be lost on the next update. To troubleshoot temporarily, duplicate the entry as a standalone configuration and record the differences. Select the intended entry before connecting so you don’t accidentally reuse the previous active configuration. A populated list and an enabled connect button don’t replace checking that the core actually starts.

VPN Permission and Per-App Proxy

The first time you connect, Android asks for permission to establish a VPN connection. Allow it so the client can receive traffic through the virtual network interface provided by Android. Here, VPN refers to the system mechanism for taking over network traffic; it doesn’t mean the remote service necessarily uses a traditional VPN protocol. Check the system status and client logs to confirm the service starts and stays running. If another VPN app is connected, stop it before testing.

Per-app proxy settings typically let you route only selected apps or bypass selected apps; these modes mean opposite things. Read the current mode before saving, then test with one target app. An app appearing in the list doesn’t prove that it’s using the proxy. Work-profile apps, separate user profiles, and some system components may run in different environments. Follow the device’s management policies and don’t try to work around organizational restrictions by repeatedly changing permissions.

The routing mode determines where traffic goes after it enters the client; per-app proxy determines which apps enter the client in the first place. They operate at different levels. If a browser is excluded, switching to global routing won’t send it through the proxy. For troubleshooting, temporarily use a simple, easy-to-understand traffic scope, then check the routing rules. Once everything works, restore per-app routing gradually to avoid maintaining two confusing sets of allow and bypass rules.

Background Restrictions and Network Changes

If the connection drops frequently when the screen turns off, check battery optimization, background activity, and manufacturer power-saving restrictions. Make only the changes the client needs for a persistent connection, then test what happens when you lock and wake the phone. There’s no need to disable power saving across the whole device. After switching between Wi-Fi and mobile data, an existing connection may need to be re-established. Confirm the phone itself is online, then reconnect. Judge subscription updates and the active connection separately; a background update failure doesn’t necessarily mean the current server is unavailable.

When moving between v2rayNG and v2flyNG, reimport the same valid subscription first, then restore routing, DNS, and per-app settings as needed. Don’t overwrite the other client’s data directory. If you need help, share redacted logs, system details, and the steps that failed; hide subscriptions, credentials, and complete QR codes. For help choosing protocol settings, see the comparison of four proxy protocols. Switching clients won’t fix every issue on the remote server.

Subscription Management: Updates, Migration, and Backups

Keep Subscription Sources Separate from Server Entries

Subscription groups store source URLs and update settings; the server list stores the connection details fetched from those sources. Keep the two separate in your mind: deleting a server entry doesn’t necessarily remove its subscription source, and the entry may reappear after the next update. Create groups by purpose or source, with names that identify actual uses such as work, testing, or backup. Don’t put the full URL in a group name. Clear group names make it easier to identify which source failed to update.

When importing a subscription for the first time, check for extra spaces, line breaks, or missing characters after pasting. Messaging apps may collapse long links, so copying the visible text might not copy the complete URL. Subscription content may also require a specific format or a client supported by the provider. If the list is empty, check whether the response is configuration data, a login page, or an error message rather than importing it repeatedly. If the URL has expired, ask the provider for a new one instead of changing random characters.

Choose an Update Route and Interval

“Update subscription (without proxy)” is appropriate when your current network can reach the source directly. It also avoids a dependency loop where you need a working connection to fetch the subscription but need the subscription to establish that connection. Updating through the proxy requires a working proxy. The two options change the request route, not the subscription format. Test each option once, check the error, and use whichever works. If no server is available, repeatedly trying to update through the proxy won’t help.

Choose an automatic update interval that suits how often the source changes, your usage, and any request limits. Stable sources don’t need frequent updates; on mobile devices, consider data use and background execution limits. If the interval is in minutes, enter the value in minutes rather than hours. First confirm that a manual update works, then wait for an automatic run. Sleep, app shutdown, or network restrictions may delay the task; scheduled updates aren’t guaranteed to run at an exact time.

An update may remove withdrawn entries and overwrite some settings managed by the source. Copy any temporary configurations you need into a separate group before changing aliases, routing associations, or transport settings. Don’t use a server’s row number as a permanent identifier; sorting may change after an update. If you use automatic server selection or group policies, confirm that the active server still meets your needs, then test regular access and routing. Don’t stop at the “update successful” message.

Backup Scope and Sensitive Data

Back up at least your subscription sources, standalone configurations, custom routes, DNS settings, listening ports, and per-app settings. Prefer the client’s built-in export or backup feature. If you need to copy data files, fully quit the client first and confirm that you’ve located the data for the instance you’re using. Copying only the program files usually won’t preserve user settings. Conversely, copying all user data may bring along paths, service states, and interface names that don’t suit another device.

For cross-platform migration, use subscription links and standard share formats where possible. Reconfigure the system proxy, TUN service, and program paths on the destination device. A configuration importing successfully doesn’t mean another core supports every extension field. Restore and test a basic connection first, then bring back routing and DNS. If the source device has many custom rules, keep a written explanation instead of overwriting the entire configuration; it’s easier to spot platform differences and unsupported fields.

After changing subscriptions, disable automatic updates for the old source and remove any entries you no longer need. If a link was exposed, deleting its local record won’t revoke anyone else’s access; replace or revoke it at the source. For update errors, follow the subscription update troubleshooting and interval guide to check the network route, time, certificates, and response. Identify where the request fails before trying to import the subscription again.

Routing and DNS: Decide Where Traffic Goes After Takeover

Understand System Proxy, TUN, and Routing Modes

The system proxy and TUN get traffic into the client; routing rules decide where it goes afterward. Global routing generally sends traffic that the client has taken over through the selected proxy outbound, but it doesn’t automatically cover every app. Split-routing modes such as bypassing mainland China use domains, addresses, or rule sets to decide what goes direct and what uses the proxy. If an app isn’t following the expected route, first check whether its traffic entered the client, then see which rule it matched.

Most routing systems apply rules in order. A broad rule near the top can override more specific rules below it. Put clear rules for domains, apps, or destinations first, followed by a fallback, and make sure the active core supports the fields you use. Don’t mix configuration syntax from different cores. Client-provided presets make a useful baseline. Before adding custom rules, export the current configuration and note what each change does and where it belongs so you can restore it later.

Understand the Context of a Rule Snippet

The snippet below is a rule from an Xray/V2Ray-style routing object that sends matching domains to an outbound named direct. It isn’t a complete client configuration; it belongs in the appropriate routing.rules section and requires an existing outbound with that name, along with usable domain rules. If the graphical client has a rule editor, use it to enter the rule. Don’t replace the entire runtime configuration with this snippet, and don’t assume every core uses the same fields.

{
  "type": "field",
  "domain": [
    "geosite:cn"
  ],
  "outboundTag": "direct"
}

type specifies the rule type, domain defines the domain matching condition, and outboundTag selects an outbound tag. The tag is an internal configuration reference and must match an existing outbound exactly. Missing rule data, a nonexistent tag, or an earlier rule taking precedence can all prevent the expected result. After editing, check that the core accepts the configuration, then review the match log for a test request. A successful save alone doesn’t prove the rule works.

DNS Resolution Paths and Domain Matching

DNS translates domain names into addresses, but proxy connections also depend on how the app, operating system, and core each resolve names. A browser may use its own encrypted DNS, and the system may cache old results. Even if the client is configured for remote DNS, requests that don’t enter the client may use another resolver. Before troubleshooting, map the path: which component makes the query, which route it takes, and which component uses the result to connect. Changing one DNS address rarely fixes every resolution issue.

Plan direct and remote DNS together with your routing rules. Domains intended to connect directly need a reachable resolution path. For proxied destinations, avoid making DNS resolution depend on a connection that hasn’t been established yet. DoH encrypts DNS queries in transit, but the service still needs to be reachable and may require bootstrap resolution. Don’t assume DoH guarantees a correct result; check timeouts, certificates, and the response.

FakeDNS uses synthetic addresses to help the core retain domain information. It suits certain traffic takeover setups, but the address mapping, routing, and DNS flow all need to work together. If an app receives a synthetic address and bypasses the core, its connection may fail. There’s no need to enable FakeDNS when the regular system proxy meets your needs. Before testing, save your current DNS settings, confirm that the core supports FakeDNS and that traffic is being intercepted, then check direct-connection apps, local network services, and recovery after exiting.

To test split routing, check at least one destination that should connect directly and one that should use the proxy, then confirm the outbound in the logs. If cached data gets in the way, clear it using the app or system’s supported method, reconnect, and test again. Don’t reset every network setting at once. For more detail on DNS fields and resolution choices, see the v2rayN DNS split-resolution guide. Keep rules simple and easy to explain before adding more specific policies.

Common Configuration Issues: Troubleshoot One Layer at a Time

Treat Startup Failures and Connection Failures Separately

First identify where the failure occurs: the app won’t open, the core won’t start, the local port is unreachable, the remote connection fails, or only webpages fail. If the app won’t start, check the architecture, system requirements, runtime dependencies, and configuration directory permissions. If the core reports an error, check configuration parsing, executable components, and port binding before changing subscriptions. Only investigate remote timeouts and authentication after confirming that local startup works.

Open the logs and repeat the failed action once. Note a few related errors and their timestamps in order. A single timeout may not be the root cause; check for an earlier DNS failure, refused connection, or unsupported configuration. Before sharing logs, hide addresses, credentials, and subscription details while keeping the error category, protocol name, and sequence of events. Publishing a full configuration with credentials won’t help diagnose the issue and can expose sensitive information.

Connection Timeouts, Authentication, and Transport Settings

For a remote connection timeout, first confirm that your network is working and the system clock is accurate. Check for typos in the address and port. If every configuration fails, focus on the local network, core startup, and traffic takeover method. If only one fails, check that server’s status and settings. Speed test results depend on the test method and destination; one failed test doesn’t prove that all traffic will fail. Try an actual connection too.

For authentication errors, check the identifier or password required by the protocol. TLS errors may also require checking the server name, certificate chain, system time, and transport settings. The connection address and the server name used for verification can differ; don’t clear a field just to reduce the number of settings. The transport path, Host, and other extension parameters must also match the server. Don’t bypass certificate verification to hide a configuration error. First check whether your connection details have expired or the server name is wrong.

If the problem started after switching cores, check whether the new core supports the protocol and extensions you use, and whether subscription conversion dropped any fields. Xray and V2Fly don’t support all the same features. Switch back to the previously working core and basic configuration, then check the differences one at a time. For a more detailed remote troubleshooting sequence, see node timeouts and connection failures. Repeatedly switching clients won’t fix incorrect settings that remain unchanged.

Quick Troubleshooting: Restore Access and Narrow Down the Cause

Finish with a Configuration You Can Explain

When troubleshooting is done, remove temporary test entries, restore only the autostart and split-routing rules you need, and check that regular internet access still works after quitting the client. Save a verified working backup with notes on the operating system, architecture, proxy mode, and key changes. If something goes wrong next time, compare recent changes before reinstalling from scratch. For the complete setup walkthrough, see the quick start guide. If you need an installer for another platform, check the downloads page.