V2Ray Setup Guide
for All Platforms

Windows: Install v2rayN and configure the system proxy

Choose between the desktop and classic WPF editions

Open the Windows downloads section and start with v2rayN. The desktop edition uses a cross-platform UI framework; the classic WPF edition is for Windows. Their layouts and settings may differ. Check the download page’s system requirements and package notes—an app with the same name doesn’t necessarily have the same runtime dependencies. If this is a managed device, confirm that you’re allowed to install software and change proxy settings.

Handle the download according to its actual package type. For an installer, follow the prompts to choose a destination. For an archive, extract all files to a writable folder and launch the app from there; don’t run it from the archive preview. If you put the app in a temporary download cache or a folder that’s cleaned automatically, its configuration, logs or bundled core may be removed. If the app reports a missing runtime, install the dependency required by that package rather than repeatedly swapping unrelated core files.

On first launch, check that the main window loads fully, settings can be saved and the configuration is still there after restarting. A standard system proxy usually doesn’t require running as administrator; start with a normal user account. If the firewall prompts you, verify which app is making the request and which network it applies to. A local proxy is generally for apps on this computer; a browser test doesn’t require opening access to every device on the network. If the system blocks the app, read the reason instead of dismissing every security warning.

Import a subscription and choose a configuration

For a single share link, copy it and use an option such as “Import from clipboard.” Add a subscription URL in the subscription group settings: create a group, enter the URL, save it and then update. Button labels may change between versions, but the sequence is the same: save the URL, fetch the list, then select a configuration to use. Seeing entries in the list only confirms that the import worked; it doesn’t mean the core is running or that a server is reachable.

After updating, check that the configuration’s group, protocol and transport settings match your provider’s instructions. A display name is just a label; it doesn’t tell you whether two configurations are identical. Subscription updates may replace entries, so copy a configuration to a separate group before editing it by hand. If you have several connection options, start with one known-good configuration instead of changing the protocol, port and TLS settings all at once. For details, see Share links vs. subscriptions: how to import them.

System proxy, TUN and permissions

Once the core is running, enable the system proxy in the client and check the address and port in Windows proxy settings. A system proxy sets an entry in the OS settings; only browsers and apps that read those settings will use it. Some apps have their own proxy settings, while others connect directly. So if the browser works but another app doesn’t, the server may not be the problem. An automatic configuration script, manual proxy or browser extension may also override the client’s settings.

TUN mode handles traffic through a virtual network interface. Its coverage differs from the system proxy, and it typically requires elevated permissions and routing changes. Enable it only if your client version, selected core and system support it. First turn off other proxy-routing methods, then grant the permissions requested by the app. If enabling TUN cuts off all network access, turn it off, confirm that the default route has been restored and return to the verified system proxy setup. Then check the logs, interface status and security software alerts.

Get-NetTCPConnection -State Listen |
  Select-Object LocalAddress, LocalPort, OwningProcess

The PowerShell commands above only show local listeners; they don’t fix connection problems. Compare the results with the actual listening port shown in the client settings. If another app is using that port, change the client’s local port and update the app’s proxy settings to match. Don’t confuse the remote server port with the local proxy port. Enabling “Allow LAN connections” changes which interfaces can listen; for a single-device setup, keep the loopback address unless you have a reason not to.

Exit, startup and upgrade considerations

Closing the window may only minimize the app to the notification area. When you’re done, clear the system proxy set by the client before quitting, so apps don’t keep trying to connect to a local port that’s no longer listening. After enabling launch at sign-in, restart and verify that the client and proxy settings behave as expected; automatic launch doesn’t necessarily mean TUN will obtain permissions automatically. Before upgrading, exit the old process and back up your settings. Afterward, check subscription groups, the selected configuration, listening ports and routing presets—not just whether the main window opens.

Linux: Install deb or rpm packages and integrate with the desktop

Check the distribution and architecture separately

Use v2rayN on Linux desktops. Open the Linux downloads section. Debian, Ubuntu and compatible distributions generally use deb; Fedora and compatible environments generally use rpm. Package format and machine architecture are separate: deb packages, for example, can be built for x64 or arm64. Check /etc/os-release and uname -m before choosing a package. Being able to download a file doesn’t mean it can be installed on your system.

The commands below use a temporary working directory to isolate the package to be installed. They assume the current directory contains exactly one matching package. Keep the real filename used for the download. Copy the selected package to the working directory, check the file list and then install it; don’t run wildcard commands directly in a downloads folder containing old packages. Use only the command set for your distribution: deb or rpm.

# Debian / Ubuntu: confirm the deb file in the current directory
ls -1 ./*.deb
sudo apt install ./*.deb

# Fedora: confirm the rpm file in the current directory
ls -1 ./*.rpm
sudo dnf install ./*.rpm

Installing through the system package manager helps handle dependencies and registers the app with the system. If the architecture doesn’t match, get the right package. If dependencies are missing, check the supported distributions and software sources. Ignoring dependencies isn’t a routine fix. After installation, launch the app from the desktop menu and save settings as your regular user. Running a graphical app as root can leave configuration files owned by root, preventing your regular account from writing to them later.

Import subscriptions and configure the desktop proxy

After launching the client, save and update a subscription group or import a single configuration from the clipboard. On Linux, remote desktops, different display sessions and terminal clipboard tools may use different selections or buffers. If import fails, first check that the graphical client received the expected text. Don’t paste a subscription URL into a public terminal log. Select a configuration and start the core, then check the local listener and startup logs before enabling the system proxy.

Linux “system proxy” settings aren’t a universal gateway used by every app. Desktop environments, browsers, terminal programs and background services may each use different settings. A proxy set in desktop network settings doesn’t mean shell commands will use it; setting environment variables in a terminal doesn’t mean desktop apps will read them. First test with an app that supports explicit proxy settings, then configure the desktop for your use case.

HTTP and SOCKS proxy ports use different protocols and can’t be interchanged; if the client supports a mixed listener, follow its documentation. Proxy environment variables in the terminal may point to an old port, making command-line tests differ from browser results. Check them carefully—shell history and variables may contain credentials, so don’t share them publicly. Use the read-only command below to check listeners, then compare each result with the client settings.

ss -lntup
ip route
ip -6 route

TUN permissions and network manager conflicts

TUN mode usually creates a virtual interface and changes routing. Being able to open the client as a regular user doesn’t mean you have permission to do those things. Prefer the privilege escalation method provided by the client. Don’t grant broad write access to the entire app directory or give unknown files permanent privileges. After enabling TUN, check the virtual interface, default route and DNS status. If the core fails to start, address any clear permission errors in the logs before changing split-routing rules.

NetworkManager, other virtual networking tools, container networks and corporate tunnels may all modify routing. If they conflict, first disable the newly added traffic capture method and restore the original network, then enable each tool one at a time to identify the cause. If local network resources are unreachable, check direct-routing rules for private addresses and routes through the virtual interface rather than sending all traffic through the proxy. If IPv4 works but IPv6 doesn’t, the two may be taking different paths; record the results separately.

Desktop login startup and upgrades

Start with the client’s built-in launch-at-login setting. If your version doesn’t have one, use the desktop environment’s Startup Applications manager to select the installed app. Launching at desktop login isn’t the same as starting a system service at boot: a graphical client depends on the user session and shouldn’t be treated as a headless service. Log out and back in to verify the setup, and check that it hasn’t started duplicate processes.

Before upgrading, exit the old process, install the new package using the same package management method and keep a backup of your user configuration. If you previously launched the app as an administrator and can’t save settings, check the owner of the configuration directory. Fix only the data directory that belongs to the client; don’t recursively change permissions on your entire home folder. For package installation and login startup, see Install v2rayN on Linux and configure autostart.

Subscription management: groups, updates and migration

Share links, subscription URLs and full configurations

vmess:// and vless:// share links usually describe one server configuration. A subscription URL typically makes an HTTP request that returns a set of entries. A full JSON configuration may include inbounds, outbounds, routing and DNS. They serve different purposes. Pasting a subscription URL into a single-server editor, or importing full configuration JSON as a share link, causes a format mismatch. Identify the content type first, then use the matching import option in your client.

A subscription URL opening in a browser doesn’t mean the client can parse it. The response could be a login page, an access notice, a redirect or an unsupported configuration format. Seeing text in a browser doesn’t mean the client accepts every field. If parsing fails, confirm that the response is actually subscription data and check which formats the client supports. Don’t keep reinstalling the client just because the page looks fine in a browser.

Access parameters in a subscription URL may grant access to your account. Don’t send the full URL to a public conversion service, include it in a public configuration example or post a screenshot of your browser history when asking for help. Before using a converter, check the input and output formats, whether you trust the service and which fields might be dropped. Conversion changes the format; it won’t fix an expired account, unreachable server or missing authentication information.

Name groups and verify updates

Create a separate group for each source and give it a short name that identifies where it came from and what it’s for. Keeping test configurations, manual entries and subscription items separate makes it easier to see what an update affects. Don’t rush to delete duplicates in a group. Compare their server addresses, protocols, ports and transport parameters first. The same display name doesn’t guarantee identical configurations, and different names may point to the same server.

Trigger the first update manually and check the result and changes to the list. After it succeeds, consider setting an automatic update frequency. This helps avoid repeated failures if the network isn’t ready or the client hasn’t started. Some clients can update “through the proxy”; use this only if an existing configuration works. Before you have a working connection, this option may make subscription retrieval depend on an exit route that doesn’t exist yet.

An update may replace or remove the currently selected entry, so check your selection afterward. If the number of entries changes, first check whether the provider changed the subscription content rather than assuming local data is corrupted. If a manually configured baseline still connects, you can narrow the problem down to the subscription request or parsing. Keeping old entries after an update fails is usually more useful for diagnosis than clearing every group and trying again.

Separate configuration data from runtime settings when migrating

Moving to another device involves at least two things: server details and local runtime settings. A share link or subscription usually covers only the former; it won’t migrate system proxy settings, listening ports, per-app routing, TUN permissions or launch-at-login. Windows file paths and Linux permissions shouldn’t be copied directly to Android either. Set up a connection from the section for your new platform, then restore your routing preferences one at a time.

After exporting a backup, verify what it includes. Some exports contain only server details; others include client preferences. Don’t assume any export includes operating-system permissions. Set encryption and access restrictions based on your device’s capabilities. If a subscription URL has been exposed, deleting the local file won’t revoke remote access; use the provider’s supported process to change the access credentials.

Core compatibility and configuration fields

V2Fly and Xray are part of the same open-source ecosystem, but their feature support isn’t identical. Switching cores doesn’t automatically translate configuration semantics to the other implementation. If you see an unknown field, an unsupported transport or a startup failure, read the specific error and check what your provider requires. Configurations such as REALITY require specific core capabilities; choose a compatible client and core instead of copying options into v2flyNG that its core doesn’t support.

For more on identifying formats, see Share links vs. subscription links. For complex configurations, read Understanding the config.json structure. Distinguish fields generated by the client from custom fields you added; a label in the interface isn’t necessarily a core parameter.

Common configuration issues: troubleshoot by layer

Start with local startup issues

First identify the layer where the failure occurs: app installation, core startup, local listener, traffic capture, remote connection, DNS resolution or the target app. Keep one repeatable test action, such as opening the same destination in the same app on the same network. Don’t change the client, configuration, DNS and routing all at once. Changing several things removes your baseline; even if the connection comes back, you won’t know which change helped.

If the client won’t open, check system requirements, package architecture and runtime dependencies. If the interface works but the Connect button immediately returns an error, check the core startup logs. Start with unknown fields, missing resources, execution permissions and port conflicts. The remote server hasn’t been contacted yet, so changing its address usually won’t help. If settings won’t save, check that the data directory is writable, that there’s enough disk space and whether the app was previously run with different permissions.

If the local proxy port isn’t listening, apps will get a connection refused or timeout error. Check the port in the settings instead of guessing a fixed value from another guide. If another process is using it, identify the process, close the conflicting app normally or change the local port. Don’t terminate system processes at random. After changing the port, update the app’s own proxy settings and the system settings too; otherwise, the core may be working while apps still connect to the old entry point.

Empty subscriptions and remote connection failures

If a subscription list is empty, first check whether the update actually completed. A failed network request and a response that can’t be parsed need different fixes. For a request failure, check URL reachability, the update route and network status. For a parsing failure, check the response format and the client’s supported formats. Make sure the URL wasn’t truncated and that you didn’t copy an account page instead of a subscription. Keep existing working entries; don’t clear every group because of one failed update.

If the core is running but every request fails, check that the right configuration is selected, its details are still valid and system time is accurate. A timeout means something wasn’t completed in time; it doesn’t by itself prove the server is broken. For authentication errors, first check credentials, account status and parameters. For TLS errors, check the server name, certificate requirements and time. Don’t treat skipping certificate verification as a standard fix.

If a configuration fails only on one network, keep the configuration unchanged and switch networks to compare. Wi-Fi, mobile and corporate networks may use different DNS paths and have different egress restrictions. If switching networks fixes the problem, keep checking the failing network and note the stage and logs. Don’t generalize the result to every client. Set protocol parameters according to your provider’s instructions; don’t swap in an option just because its name looks similar.

Browser works, but another app doesn’t

First check whether the failing app reads the system proxy, has its own proxy settings, is excluded by the Android app list or requires UDP. HTTP proxy, SOCKS and TUN have different coverage, and you’ll also need to check whether the remote protocol supports the traffic in question. A client’s built-in test may only check one kind of connection; it doesn’t prove that the target app’s full workflow works.

For DNS problems, compare the resolution and connection errors, and distinguish system DNS, client DNS, browser-specific DNS and Android Private DNS. Don’t disable IPv6 based on a single failed domain. First compare the IPv4 and IPv6 routes and logs, then make a targeted change if needed. If you can’t reach a local service, check private-address routing and TUN routes before sending local traffic through a remote exit.

Stop traffic capture, restore network access and prepare logs

To restore normal network access, first disable TUN or disconnect the Android client, then clear the system proxy set by the client and quit the app. If it has already crashed, check whether the operating system still has a local proxy configured. Don’t remove a proxy originally set by your company; undo only the settings added or changed for this setup. If the network still doesn’t recover, check the default route and DNS status, reconnect the current network service if needed, then restart the device.

When asking for help, include the platform and architecture, client name, stage where the problem occurs, steps already tried and a redacted error excerpt. Remove subscription URLs, authentication fields, full user IDs and unnecessary network details; keep only the context needed to diagnose the issue. Debug logs may include destinations you’ve visited, so restore the normal log level when you’re done. A problem you can reproduce reliably is more useful than a large dump of unfiltered logs.

Use this page as a reference for troubleshooting by layer. To repeat the minimal connection setup, return to the Quick Start Guide. For a package with the right architecture, visit the client downloads page. For complex fields and outbound references, see Understanding configuration structure. Keep platform setup issues separate from core parameter issues.