For anyone setting up v2rayN on a desktop for the first time. Choose the package for your operating system and processor, then make sure the main window and proxy core both start. Import a known working node and test the system proxy in your browser. Finally, check that direct connections work again after clearing the proxy. This helps separate installation, node, and app configuration issues.
First Launch on Windows and macOS
Make sure the package matches your computer's processor architecture. On Windows, go to Settings → System → System Information (called About on some versions) and check System type. An x64 package is for an x64 processor, so don't rely only on whether Windows is 64-bit. On macOS, check Chip or Processor under About This Mac: choose arm64 for Apple silicon or x64 for an Intel processor.
Launch Based on Package Type
Windows
- If you downloaded a ZIP, select Extract All first. Open
v2rayN.exefrom the extracted folder. Don't run it from the archive preview or drag the main executable to your desktop by itself. - Choose a permanent folder that the current account can write to. If you downloaded an EXE with an installer, follow the setup wizard and launch the app from the Start menu; the ZIP steps don't apply.
- Desktop and WPF are interface package options, not protocol choices. For your first setup, keep just one version to avoid two instances listening on the same port.
macOS
- Open the DMG and drag v2rayN into Applications. Once copying is complete, eject the disk image and launch the app from Applications instead of running it from the mounted window.
- If you downloaded an archive, extract it first, then move the complete app to Applications. Don't extract a standalone executable with the same name from the app bundle and run it separately.
- If macOS blocks the app, verify the package source, architecture, and release notes. If macOS says the app is damaged, download the correct package again. Don't disable system security checks as a troubleshooting step.
First, make sure the main window opens and that you can launch it again after closing it. Once that works, import a node and configure the system proxy.
Runtime Requirements and Local Ports
If Windows shows “You must install .NET to run this application” after you double-click the app, check the framework name, major version, and architecture in the message. For example, if it says Microsoft.WindowsDesktop.App 8.0 x64 is missing, install the matching .NET 8 Desktop Runtime x64. Installing only the standard .NET Runtime for the same major version may not be enough for a desktop app. Requirements vary by package, so don't assume .NET 8 is always required. If you're using a package marked self-contained and the main window opens but connections fail, check the core logs instead of reinstalling the runtime.
Check the local listener settings under Settings → Preferences. Recent versions commonly use a local mixed port that accepts both HTTP and SOCKS requests; older versions may use separate ports. These numbers are examples of common configurations, not a way to identify the proxy type. When configuring an app manually, use the current settings, set the address to 127.0.0.1, and enter the port for the appropriate listener. This is not the node's remote address, and you don't need to enable “Allow connections from the LAN” for local use.
If the logs show address already in use, quit the other instance or app using that port. If you need to change the port, save the new value in Preferences, restart the core, and reapply the system proxy. Update any apps where you entered the proxy manually, too. Changing the client's listening port alone won't stop a browser from sending requests to the old port.
Importing Nodes and Choosing a Core
v2rayN is the desktop interface for managing nodes and launching a core. The core establishes connections using each node's configuration. For your first setup, import one subscription or a known working node, then set it as the active server. Start with the default core settings. Change the core only if the node requires a specific transport or security option, or the logs clearly show that a setting isn't supported.
- If you have a subscription URL, open Subscription Group → Subscription Group Settings, add a group, paste the full URL into Address (url), and save. Back in the main window, use the Subscription Group menu to update without a proxy. If your current network can't reach the subscription URL, check the subscription's access requirements instead of repeatedly changing cores.
- For a single
vmess://orvless://share link, copy the entire link and choose Servers → Import batch URLs from clipboard. You can also press Ctrl + V while the main window is active (Windows). Don't paste a share link into the subscription group's address field. - Make sure the node appears in the current group, then double-click its row to set it as the active server. Check the logs for core startup errors. To review the core type, open Settings → Preferences and look for Core Type Settings; wording may vary between releases.
Xray Core
RecommendedIf the node explicitly uses VLESS with REALITY, use Xray and keep the transport and security settings imported from the link. Xray also supports common VMess configurations, so a link starting with vmess:// isn't by itself a reason to switch cores.
Best for: first-time VLESS + REALITY setup, or common VMess nodes whose provider doesn't specify another core.
V2Ray Core
If this option is available in your version and the node documentation explicitly requires V2Ray for a particular VMess configuration, follow the documentation. Don't assume missing core files, port conflicts, or node timeouts are compatibility issues.
Best for: VMess setups with specific version and configuration requirements.
A successful subscription update only means the client received a list; it doesn't mean every node in it will connect. Core Type Settings may affect other nodes using the same protocol. Note the original setting before changing it, and change one thing at a time. If the error says the core executable can't be found, check whether your package includes the selected core and was fully extracted. Don't troubleshoot by changing protocol fields.
System Proxy and Browser Testing
Start by having your browser use the system proxy. Don't enable TUN or change the browser's manual proxy settings at the same time. This tests whether the app's traffic reaches the local proxy. Routing comes next: once traffic reaches the core, routing rules determine whether it connects directly or through a node. Enabling the system proxy doesn't route every app through the proxy or send every destination through a node.
| System proxy menu option | What it does | What to choose for your first setup |
|---|---|---|
| Set system proxy automatically | Applies system proxy settings for apps that follow them. | After setting a node as active, use this to test browser connectivity. |
| Clear system proxy | Removes system proxy settings. It doesn't quit the app or clear proxy settings saved within other apps. | Use after testing to restore direct connections. If your computer has a work proxy, note its original settings so you can restore them. |
| Do not change system proxy | Leaves the current system proxy unchanged and doesn't clear settings left behind earlier. | Use this to configure a local proxy manually for one app or to keep existing system settings unchanged. |
- Open System Proxy from the v2rayN tray menu or main window, then select Set system proxy automatically. On Windows, check the current settings under Settings → Network & Internet → Proxy. On macOS, go to System Settings → Network → your current network service → Details → Proxies, then check the address and port.
- In a browser that follows the system proxy, open a known working HTTPS page and refresh it once while checking the v2rayN logs. A request in the logs only confirms that traffic reached the core. To confirm it went through a node, check that the request's outbound route uses a proxy rather than a direct connection.
- When testing is complete, select Clear system proxy and open a page that normally works with a direct connection in the same browser. Once you've confirmed direct access is restored, quit the app. This prevents the app from sending requests to the local proxy port after the core has stopped.
Common First-Launch Problems
Nothing happens when I double-click. Is the runtime missing?
First, check whether v2rayN is already running in the system tray or menu bar; the window may simply be behind other windows. If there is no process, check the architecture, extracted folder, and any runtime prompt. If the main window opens but the core won't start, read the main window's logs and fix the first startup error listed.
The latency test shows a number, but why won't web pages load?
A latency test doesn't mean your browser is using the proxy. Set the node as active and apply Set system proxy automatically, then check that the port shown in system settings matches the core's listening port. If no request appears in the logs when you refresh a page, check whether the browser has its own proxy configured or an extension is handling traffic.
The browser works, but another app still can't connect. Why?
First, check whether the app uses the system proxy. If it has its own proxy settings, enter the local listener using the HTTP or SOCKS type it supports, then test it separately. For apps that don't support the system proxy and have no manual proxy settings, switching v2rayN system proxy modes repeatedly won't change how they connect.
Why can't I open even direct websites after quitting v2rayN?
Open v2rayN again and select Clear system proxy. If the app won't open, go to your system's proxy settings and remove the local proxy left by this setup. If your computer already had a proxy required for work, restore the values you noted earlier. If only one app still can't connect, check its own proxy settings.