V2Ray Setup for Every Platform

Get Your System and Connection Details Ready

Check Your OS, Architecture, and Client Roles

Before downloading, note your operating system, processor architecture, and account permissions. Use v2rayN on desktop platforms and v2rayNG or v2flyNG on Android. The client displays server lists, stores subscriptions, generates configuration, and manages the proxy entry point. The core handles protocol connections and traffic forwarding. Installing a client does not provide a working server; you need server details separately. Don't copy an application directory from another operating system: interface files, core binaries, and permission models may differ.

Check your processor architecture in system information rather than guessing from the device's appearance. Choose Apple Silicon for Macs with Apple chips and Intel for Intel Macs. The Windows downloads on this site are for x64; on Linux, check both the architecture and package format. Most Android devices use arm64, but check the supported architecture on older devices. If the architecture and package don't match, the installation failure is a package-selection issue—not a reason to change your network, subscription, or server settings.

Gather Subscription and Server Details

Get the subscription URL or a complete server share link from your provider. A subscription URL retrieves a server list; it isn't a regular webpage URL or an account sign-in page. For manual setup, you'll need the server address, port, protocol, authentication details, and transport settings. Encrypted transports may also require fields such as a server name, path, public key, or fingerprint. If any details are missing, refer to the original instructions rather than substituting similar-looking fields or switching cores at random.

Treat subscription URLs as credentials. When copying one, avoid leading or trailing spaces, line breaks, punctuation added by a messaging app, and accompanying text. Don't post the full URL in public forums or share screenshots that show it. Before moving to another device, back up your configuration and distinguish a client settings backup from a server share link: the former may include groups, routing, and interface options, while the latter often contains just one connection. Before sharing logs, check them for server domains, account identifiers, and subscription details.

Start with a Configuration You Can Roll Back

Before installing, confirm that your system can access commonly used websites without a proxy, and note the current proxy status of your network interface. Temporarily quit other apps that modify the system proxy or use virtual adapters; there's no need to uninstall them. Work or school devices may restrict network settings through management policies. If an option is unavailable, check your permissions rather than assuming the client is at fault. Make sure your system date, time, and time zone are correct—certificate checks and some protocol authentication depend on them.

For the first test, use one client, one server, and one way of routing traffic. Start with the system proxy and test in a browser before trying TUN. Change one setting at a time and note what happens before and after; changing ports, routing, and DNS together makes it hard to find the cause. Clear the proxy settings you changed before finishing so they don't point to a local port that's no longer running. If installation fails later, save the exact error and steps you took; that makes it easier to distinguish download, permission, and connection issues than a note that it "doesn't work."

Install v2rayN on Windows

Choose the Desktop or Classic WPF Edition

Open the Windows downloads section and check your system architecture before choosing the Desktop or Classic WPF edition. Desktop has a newer cross-platform interface; Classic WPF keeps the familiar Windows interface. Both editions manage proxy connections. The interface doesn't determine server quality. Start with one edition and complete setup before switching if you run into compatibility issues. Running both at once can cause local port conflicts and make it difficult to tell which instance last changed the system proxy.

Run the installer and choose a location you can write to when prompted. If Windows displays a source or permissions warning, check the file's source and publisher before deciding whether to continue; don't disable system security altogether. If the app explicitly reports a missing runtime, install the runtime required by that package. If the app won't open at all, troubleshoot installation and runtime issues first. If it opens but the core fails to start, check the logs. These are different problems and won't be solved by changing the same network settings.

Import a Subscription and Choose a Server

Open the main window, go to “Subscription Groups” > “Subscription Group Settings,” add a group, enter a note and URL, then save. Leave the filter field blank for the first import so you don't filter out every server. Back in the main window, choose “Update Subscription (without proxy).” If your subscription service requires a proxy and you already have a working connection, choose “Update Subscription (through proxy)” instead. Updating through a proxy requires an existing connection; it can't rely on a server that hasn't been imported yet to establish its own connection.

After updating, confirm that the group contains servers, then set one as the active server. Menu locations may vary by version; use the “Set as active server” option shown in your client. A test result reflects only the conditions at the time—it doesn't mean every website, video, and download will work. Open a frequently used secure website and check whether the client logs a corresponding connection. For authentication failures, check the original server details. For timeouts, investigate server reachability, the local firewall, and routing separately.

Set Up the System Proxy, Then Consider TUN

From the tray menu, choose “Set system proxy” to route traffic from apps that follow the Windows system proxy through the client's local entry point. “Clear system proxy” removes that entry point; “Do not change system proxy” leaves the current settings as they are and doesn't clear an old address. After making changes, check “Settings → Network & Internet → Proxy” and make sure it doesn't point to a closed app. Browser extensions, app-specific proxy settings, and workplace policies may override the system setting, so check them separately.

If you need to route traffic from apps that don't use the system proxy, enable “TUN mode.” Follow the client prompts to elevate permissions or install required components; a permission prompt by itself doesn't mean setup failed. Close other virtual networking tools first and save the exact error if administrator approval fails. If all network access stops after TUN starts, turn TUN off and confirm that the system recovers before checking the virtual adapter, routing, and DNS. Don't leave a broken TUN active while repeatedly changing browser proxy settings; those are separate troubleshooting paths.

Fix Port Conflicts and Settings Left Behind After Exit

If startup reports that an address is already in use, close duplicate instances first, then check the local listening port. The command below is only for finding a process ID; replace the port with the one shown in the client settings. Check the process name in Task Manager before taking action—don't end an unfamiliar system process. Alternatively, change the client to an unused port and update any apps that rely on the old one.

netstat -ano | findstr :10808

Before exiting normally, turn off TUN, then clear the system proxy settings you changed. If the app crashes and your browser loses access, check whether the system proxy still points to a loopback address before reinstalling the client. Back up your subscription and any necessary settings before upgrading. After the upgrade, check that your old configuration loads before restoring custom routing rules one at a time. If security software blocks a file, check the specific event and file path. Don't exclude an entire drive or keep moving the installation folder to hide the underlying issue.

Install v2rayN on macOS

Choose the Installer for Your Mac's Chip

Choose “About This Mac” from the Apple menu and check the “Chip” or “Processor” field. Select Apple Silicon for an Apple chip or Intel for an Intel processor. Open the macOS downloads section and get the matching disk image. Open it and follow the installer prompts to move the app to Applications. Once copied, eject the disk image and launch the app from Applications. Running it from the disk image leaves the app in an unstable location and can make it unclear which copy has been authorized.

If macOS blocks the app on first launch, read the warning carefully. Once you've confirmed the source, check “System Settings → Privacy & Security” for an option to open this app, then follow the system prompts. Continue only if macOS explicitly allows it; don't remove security attributes from unrelated files in bulk. An “app is damaged” warning doesn't necessarily mean the proxy configuration is wrong. First download an installer for the correct architecture again, make sure the copy completed, and check system compatibility.

Add a Subscription and Check the Menu Bar

Launch v2rayN and add a note and subscription URL under “Subscription Group Settings.” Save, choose “Update Subscription (without proxy),” check that servers appear in the list, and set one as the active server. If direct updates fail, try “Update Subscription (through proxy)” only when you already have a working connection. The menu bar icon lets you show the main window and switch proxy options. Its presence only means the app is running; it doesn't confirm server authentication or system proxy setup.

From the menu bar icon, choose “Set system proxy.” macOS may ask you to authorize changes to network settings. Follow the prompt and enter credentials for a local account with the required permissions—not your subscription account password. Then open “System Settings → Network,” select the network service you're using, and check “Details → Proxies.” Wi-Fi and Ethernet are separate services, so recheck the proxy status for the active interface when you switch connections.

System Proxy Permissions and TUN Permissions Are Separate

The system proxy primarily affects apps that follow system settings. If a terminal tool or standalone app doesn't use the proxy, that doesn't mean the browser's system proxy is broken. Check whether the app has its own proxy setting before considering TUN. Enabling “TUN mode” may require additional administrator permissions to create a network interface or change routes. Authorization for the system proxy doesn't also grant TUN permissions; test each separately.

Before approving a request, confirm that it's from the client you just installed and follow the necessary prompts. If the administrator password is accepted but setup still fails, check whether device management policies restrict the account or other network software is routing traffic. If the network works again after you turn off TUN, the issue is likely in the traffic-routing path. Keep the regular system proxy for comparison and don't change server authentication at the same time. If your work network already uses a dedicated connection, check route priorities before combining the two.

Troubleshoot Wake from Sleep and Network Changes

After waking your Mac from sleep, switching hotspots, or reconnecting to Wi-Fi, the existing connection may need to be re-established. First confirm that macOS has an IP address, then try selecting the server again or restarting the client's connection. If only one app fails, quit and reopen it so it doesn't reuse an old connection. If all apps fail, turn off TUN and the system proxy to test a direct connection. Don't assume the underlying network is back just because the menu bar icon is still there.

Before quitting the client, turn off TUN, choose “Clear system proxy,” then exit. “Do not change system proxy” preserves the current settings; it doesn't remove a leftover proxy. If webpages stop loading after an unexpected exit, check the proxy page for the active network service for a loopback address and port. If you're asked to authorize the app again after replacing or upgrading it, check the path of the running copy. Having one copy in Downloads and another in Applications can lead to authorizing the old one while launching the new one.

Install v2rayN on Linux

Check the Architecture and Package Format

Before opening the Linux downloads section, check your processor architecture and your distribution's package system. x64 and arm64 require different binaries; deb and rpm use different package managers, so don't mix them just because both filenames contain “Linux.” Debian-based distributions generally use deb; distributions that use RPM packages generally use rpm. If you're unsure, check your distribution in system information or your software manager, then use the command below to confirm the machine architecture.

uname -m
cat /etc/os-release

The output x86_64 usually corresponds to x64, and aarch64 usually corresponds to arm64. The installation files here may not support other architectures. The desktop client requires a working graphical session; this desktop installation guide isn't for command-line-only servers. Remote desktops, lightweight desktop environments, and graphical sessions inside containers may also lack tray or permission services. A package manager accepting the installer doesn't guarantee that all desktop integration requirements are met.

Install with Your Software Manager

After downloading the matching package, open it in your distribution's software manager where possible. Review dependencies, installation location, and permission prompts before proceeding. If dependencies are missing, save the package manager's full error and resolve it using your distribution's recommended method. Don't copy shared libraries from another distribution or symlink libraries from a different architecture. Once installed, launch the client from the application menu and run the graphical interface as a regular user. Elevate permissions only for network operations that explicitly require it.

If the app appears in the application menu but no window opens, check whether it minimized to the tray and whether your desktop environment displays tray icons. Some desktops hide these icons by default; configure the desktop or install a compatible component rather than starting multiple instances because you can't see the icon. To inspect startup errors from a terminal, use the actual path to the installed executable instead of guessing based on another distribution's directory layout. Graphics library errors and subscription update errors occur at different stages.

Import a Subscription and Check Desktop Proxy Coverage

Add the subscription URL under “Subscription Group Settings,” save, update the subscription, and set an active server. Don't add server filters yet; first confirm the original subscription can be parsed. Then try “Set system proxy” and check the proxy entry in your desktop network settings. Linux desktops vary in how they store and read proxy settings. Some apps use only their own settings, while some command-line tools read only environment variables, so a desktop proxy setting doesn't mean every program is routed through it.

If a browser works but your software manager doesn't, check whether the software manager needs its own proxy settings and whether its background service inherits your user session settings. Don't expose the local listening address on every network interface to fix an issue with a local app; that may broaden access without making the app use the proxy. If a command-line proxy is required, configure it using a protocol the app supports and test it in the same terminal session. Its effect changes when you close that terminal or unset the variables.

Set Up TUN and Resolve Permission Issues

If you need to route more traffic, enable TUN in the client and follow the permission steps for your distribution and client version. Virtual interfaces, routing, and DNS changes usually require extra permissions; running your entire desktop session as an administrator isn't a substitute. If TUN fails to start, check whether the logs point to insufficient permissions, interface creation failure, or an unavailable helper component, then follow the relevant troubleshooting path. Check for the kernel's TUN device only if the error indicates it's needed.

Once TUN is active, compare results using the same website and app. If local network access stops working, check whether routing is incorrectly capturing the local subnet. If only domain names fail, check how the system resolver works with the client's DNS settings. Save your existing routes before changing anything if you're using a work network, container network, or virtual machine bridge. Before exiting, turn off TUN and restore the desktop proxy. Keep a backup of user settings before upgrading, and don't mix old binaries with components from a new installation directory.

Install an Android Client

Choose v2rayNG or v2flyNG

Open the Android downloads section and start with v2rayNG, which uses the Xray core. Consider v2flyNG if you already have a V2Fly configuration or need to compare its behavior. The apps use different cores, so not every configuration can be moved between them unchanged. For connections that rely on specific core features such as REALITY or XTLS Vision, check client support first. A successfully imported share link doesn't prove that every underlying setting was recognized.

In most cases, start with the arm64 package. If you're unsure of your device's architecture or installation reports an incompatibility, check the device information and consider the universal version. Open the installer in the system file manager and allow this installation from the current source when prompted. You can revoke that installation permission afterward rather than leaving it enabled. If the system reports a signature conflict, check whether an app with the same name is already installed from another source. Back up its configuration before taking action; uninstalling immediately may erase subscriptions and routing settings.

Import Connection Details and Update the Subscription

Open the client and use “Subscription Group Settings” or the subscription management option in your current interface. Add a note and the complete subscription URL, then update. If you have only a single share link, use the clipboard import option. QR code import requires camera access; grant it only when using that feature. If fetching the subscription fails, check whether the keyboard added spaces, you copied the webpage title instead of the URL, or the link has expired. Switching between Wi-Fi and mobile data can help test whether the subscription URL is reachable directly.

After the list updates, select a server and start the connection. Check latency tests separately from actual internet access: some tests rely on the active connection, while others only test the server port. Their results aren't interchangeable. First open a frequently used website, then test your everyday apps. If one client works and another doesn't, compare core support, transport settings, and routing—not just the server name. Entries with the same note may use different ports, protocols, or subscription filters.

Approve Network Routing and Set App Rules

When Android connects for the first time, it usually displays a VPN connection request. This is the system's authorization for the app to route network traffic. Check the app name in the request before approving, then check the system connection indicator and client logs. This isn't the “Set system proxy” menu used on desktop systems, and there's no need to point your phone's Wi-Fi proxy to a desktop port. Android generally can't keep two apps using the system VPN connection active at the same time, so stop any conflicting app first.

Before setting up app-based routing, check what the app list means in your interface. Selected apps may be routed through the proxy, or—when a bypass option is enabled—excluded from it. After saving, test one app on the list and one that isn't. Don't change the app list and domain routing at the same time, or it'll be hard to tell which layer determined the route. Encrypted DNS in a browser, an app's own proxy, and system network settings can also create separate paths; track them individually.

Handle Background Restrictions and Network Changes

If the connection works at first but fails after you lock the screen, check whether the system is restricting background activity. Allow the client to run in the background as needed and keep its connection notification. Battery management settings vary by manufacturer, so follow the instructions for your device. There's no need to remove background restrictions for every app. If you enable always-on VPN or the option to block connections without a VPN, understand the effect: when the client stops, Android may intentionally block other network access rather than the server suddenly failing.

After switching from Wi-Fi to mobile data, wait for the network to come online, then reconnect in the client. If only mobile data fails, compare DNS resolution and server port reachability on that network. If all networks fail, check the subscription status and authentication details first. Stop the connection using the client's stop button and confirm that the system connection indicator disappears. When moving to a new device, approve system permissions again rather than copying the old device's authorization state. For core-specific migration issues, compare settings against Xray vs. V2Fly: Core Differences.

Manage Subscription Groups and Migrate Settings

Separate Subscription Updates from Server Connections

A subscription update downloads and parses a server list; a server connection routes traffic to the selected remote server. They may access entirely different addresses. A successful update only confirms that the list was retrieved, not that every server can connect. A working server doesn't mean the subscription URL is still valid. Save errors from subscription updates separately from server connection errors. Don't mistake an error page for a protocol authentication failure, or keep refreshing a subscription to fix a local port conflict.

Create a separate group for each subscription source in “Subscription Group Settings.” Use the note to record its purpose or a short source name, and keep the URL unchanged. For the first import, leave filters blank and confirm the list is complete before narrowing it down. Filter matching varies by interface; check the field description instead of assuming plain text is a regular expression. If the list is empty after an update, remove the filter and update again, then check whether the service actually returned an empty list. Don't delete the whole group right away.

Choose How and When to Update

Use “Update Subscription (without proxy)” when the subscription service is directly accessible. “Update Subscription (through proxy)” requires an existing working proxy connection; use it when direct access fails but the current proxy still works. A new installation with no active server usually can't create its own connection to update through a proxy. First check whether your provider offers a direct retrieval method or, following its instructions, import a valid connection. Don't use details from an unknown source to bypass this requirement.

Set an automatic update interval based on your provider's limits and how often the list changes. Frequent requests don't make the list more reliable. If you get rate-limited, stop retrying and wait for the service's stated retry window. An expired URL, disabled account, or subscription format change requires checking your account with the provider; changing DNS won't fix it. After an update, make sure the active server is still listed. If it was removed or renamed, select another one—an old note still shown in the status area doesn't mean the server is available.

Keep Manual Servers and Essential Backups

Manage manually added connections separately from subscription-generated ones. Avoid changing the address, port, or note on a subscription entry to save custom settings; an update may overwrite them. If you need a temporary adjustment, copy the entry to a separate manual group and record why you changed it. Server names aren't unique identifiers, and entries with the same name may use different transport settings. During migration, compare all fields rather than merging entries by name. Before deleting a group, check whether it contains your only copy of a manually added connection.

Before upgrading or switching devices, save your subscription URLs, manual connections, routing rules, and any necessary client settings. Backups often contain authentication details, so store them securely and keep them out of public sync folders. Between operating systems, migrate reusable server details first, then set up system proxy and TUN permissions again. Don't overwrite executable paths, network interface names, or elevation settings on the new system. After restoring, enable just one connection and verify it works before restoring automatic updates, app-based routing, and other custom options.

Limit Where Sensitive Information Is Shared

When sharing a subscription screenshot, include only the error type, time, and action. A share link may encode authentication details in the full string; treat it as confidential even if it doesn't look like a password. Before asking for help, check exported files, logs, and QR codes. Don't post a complete configuration publicly. If a link has been exposed, update your subscription credentials using your provider's instructions; deleting a public post can't revoke a URL that's already been copied. To organize multiple sources, see Managing Multiple Subscription Groups and Filtering Servers, then add filters gradually.

Configure System Proxy, Routing, and TUN

First Check Whether Traffic Reaches the Client

The system proxy determines which local entry point an app sends requests to. Routing determines which outbound a connection uses after it enters the core. These are two separate stages. If an app doesn't use the system proxy, changing routing rules usually won't affect it. If traffic has reached the core but a rule sends it direct, turning on the system proxy again won't route it to a remote server. Check the logs to confirm that a request reaches the client, then inspect its destination, matching rule, and outbound. This avoids guesswork across unrelated settings.

“Clear system proxy” removes the system proxy entry point; “Set system proxy” writes the current client's entry point; and “Do not change system proxy” preserves the existing settings. The last option doesn't restore the previous state or switch to another global mode. If the system still points to a local port after the client exits, apps that follow the system proxy may lose access. To use multiple network tools together, decide which one is responsible for setting and restoring the proxy. Don't let two apps repeatedly change the same system settings.

Understand Presets and Rule Order

The tray routing menu's “Bypass mainland China,” “Blacklist,” and “Global” options switch preset strategies. What each preset covers depends on its current rules, so don't infer its behavior from the name alone. A global strategy generally routes traffic that has entered the proxy path through the proxy outbound; it doesn't force every app to use the client. To preserve access to local devices, check how private subnets and local domains are handled. On work networks, also account for internal DNS and private address ranges instead of copying public rules as-is.

Routing rules are generally checked in order. Broad conditions near the top can take precedence over more specific rules below them. The snippet below shows a routing object that splits traffic by domain and private address. It isn't a complete client configuration and shouldn't be pasted into a field that accepts only a rules array. Before merging it, check the core's syntax, what the editor expects, and whether the full configuration defines the outbound tag. An undefined tag can invalidate the rule or prevent the configuration from starting.

{
  "routing": {
    "domainStrategy": "AsIs",
    "rules": [
      {
        "type": "field",
        "domain": ["domain:example.com"],
        "outboundTag": "proxy"
      },
      {
        "type": "field",
        "ip": ["geoip:private"],
        "outboundTag": "direct"
      }
    ]
  }
}

In this example, domain matches domains, ip matches an address or address range, and outboundTag points to a defined outbound. domain:example.com is a domain-matching example for illustration; geoip:private requires the core to have access to the corresponding rule data. AsIs doesn't actively resolve every domain for each routing match, so address-only rules may not match destinations that are still passed in as domain names. Don't replace all DNS policies just to make one rule match.

Check DNS and In-App Settings Separately

If websites fail by domain name while other connections work, check name resolution—but don't stop after switching to a public DNS server. The system, browser, app, and core may each handle DNS differently. With encrypted DNS enabled, a browser may use a different path from the system. TUN can also change how domain names map to destination addresses. Keep the test path simple, note whether requests reach the client, then decide whether to change system DNS, app settings, or core configuration.

TUN expands the range of traffic the client can route; it won't fix invalid authentication, an expired subscription, or an unreachable remote server. Before enabling it, confirm administrator permissions and close other apps that route traffic. After enabling it, test domain access, local network access, and apps that don't follow the system proxy separately. If something breaks, undo the most recent change and return to a working system-proxy setup before adding settings one at a time. Keep necessary exceptions for local networks so printers, network storage, and work services don't become unreachable.

Troubleshoot Common Configuration Issues

Narrow Down the Problem by Stage

First identify whether the problem occurs during installation, startup, subscription updates, or web access. For installation failures, check architecture, OS compatibility, and permissions. If the window won't open, check the runtime and graphical session. If the core won't start, check configuration syntax, component paths, and port conflicts. If a subscription update fails, check the URL and retrieval path. Troubleshoot website connections only after both the app and core start normally. Reinstalling repeatedly without separating these stages won't fix server-side problems and may erase useful settings for comparison.

If the client says it's connected but webpages won't load, turn off TUN and clear the system proxy to check the underlying network. If direct access fails too, troubleshoot Wi-Fi, the gateway, system DNS, or a sign-in page first. If direct access works, open the client, enable only the system proxy, and select a server with complete connection details. Check whether failure is immediate or a timeout, whether all sites fail, and whether other apps are affected. Each result points to a different next step; a connection icon alone doesn't tell you what went wrong.

Use Logs to Distinguish Port Conflicts, Authentication, and Timeouts

A local listener failure usually happens while the core starts; check for duplicate instances and port conflicts. An authentication rejection usually points to account details, protocol settings, or the service status. A timeout requires further checks of DNS resolution, network reachability, and the remote server's response. For certificate errors, check the system time, server name, and transport settings; disabling certificate verification isn't a general fix. Save the full error and the time it occurred. That's more useful than a screenshot of one English word and helps you compare results before and after a change.

If only some servers in a subscription fail, compare their protocols, transports, ports, and exit regions to see whether they share a configuration. If every server fails and the core logs no connections, the issue is more likely the app entry point or local traffic routing. If only one site fails, check routing, DNS, and the destination service before resetting the entire client. Test servers over the same network using the same method; results from different probes aren't directly comparable. For a detailed selection guide, see How to Compare Server Latency, Multipliers, Regions, and Protocols.

Restore a Working Baseline

After several rounds of changes, back up the current settings and create a minimal configuration: one subscription group, one server, default routing, and one traffic-routing method. Temporarily turn off custom rules, app lists, and automatic switching. Once the baseline works, restore one setting at a time and retest the same website and app. If something fails right after you restore a setting, keep a record of the difference; there's no need to reinstall the whole app. Resetting isn't the first step. Use it as a diagnostic only after backing up your data and deciding what you'll restore.

When asking for help, include your operating system, architecture, client name, exact steps, full error text, and comparison tests you've already run. Logs can show which connection stage failed, but remove subscription URLs, authentication fields, and identifying personal information before sharing them. Don't publish a complete backup file. For more detailed web access troubleshooting, see v2rayN Connected but No Internet: Troubleshooting Checklist. If you missed a step during initial setup, return to the quick-start guide and follow it from the beginning.