v2rayN First-Run Setup Guide: Windows and macOS Installation, Initial Settings, and Common Issues

Choose the right desktop build before installing

v2rayN is a desktop proxy management client. It stores nodes, runs proxy cores, switches the system proxy, and applies routing rules. It is not a node service. Before getting started, prepare a valid subscription URL or complete node parameters, and confirm the computer's operating system and runtime environment.

Windows users typically see two desktop variants: WPF and Avalonia. The WPF build follows the native Windows interface and suits Windows-only use. The Avalonia build supports Windows, macOS, and Linux with a more consistent layout across platforms. macOS users should choose Avalonia rather than copying a Windows executable and trying to run it.

After downloading, extract the archive completely to a fixed directory, such as D:\Apps\v2rayN on Windows. Do not run the program long-term from an archive preview window, and avoid placing it in a temporary folder that is frequently cleaned. The program needs a stable location for configuration, logs, and core files.

First launch: check the core, ports, and logs

After opening the main program, do not immediately judge whether a node works. First check the status bar, core type, and local listening ports. If the core has not started correctly, imported nodes may appear in the list but cannot establish a real proxy connection.

Different versions or migrated configurations may use other ports, so the numbers above are only common starting values. Use the local listening settings under “Settings” → “Parameter Settings” as the source of truth. Browsers, download tools, and development tools configured manually must use the address and port shown there.

1. Extract completely

   Extract every file to a fixed directory before launching the main program. Make sure the directory is writable, and keep the subdirectories containing the core, configuration, and logs.

2. Select a core

   Go to “Settings” → “Parameter Settings” → “Core Type”. For everyday use with VLESS, REALITY, or newer transport configurations, Xray is usually the preferred choice.

3. Check the ports

   In Parameter Settings, check the SOCKS and HTTP listening ports and make sure neither is already used by another local proxy program.

4. Check the logs

   Return to the main interface and open the log panel. A healthy state should show that the core started and listening succeeded, rather than repeating the same error continuously.

5. Save and restart

   After changing the core or listening parameters, save the settings and select “Restart Service” so the new parameters are actually loaded.

A missing core usually appears as an immediate stop after launch, log messages saying that the core file cannot be found, or failed tests for every node. First confirm that you downloaded the complete desktop package rather than a stripped archive containing only the main program. Then check that “Core Type” points to a core that actually exists in the current directory. Restart the service after switching cores.

Import a subscription and make the first connection

A subscription URL retrieves nodes and their protocol parameters in bulk. It may contain VMess, VLESS, Trojan, and other configurations. A common v2rayN setup pairs the Xray core with VLESS, REALITY, or VMess. After import, the client writes the server address, port, user ID, transport, and security parameters supplied by the provider into the local list.

1. Add a group

   Open “Subscription Groups” → “Subscription Group Settings”, choose Add, enter a recognizable label, and paste the complete subscription URL.

2. Update the subscription

   Save it, then go to “Subscription Groups” → “Update All Subscriptions” and wait for the node list to refresh. Do not click repeatedly during the first update.

3. Test latency

   Select a group of nodes and run a real latency test. On a typical home connection, usable results are often around 40–250 ms. A timeout only means that this probe did not finish.

4. Set as active

   Double-click the target node, or use the context menu to set it as the active server. Confirm that the selected node appears in the main interface status bar.

5. Start the proxy

   Choose the appropriate system proxy mode, then open a browser and visit a regular webpage while checking whether the logs show new connection entries.

If the subscription updates successfully but the list is empty, first confirm that the current subscription group is enabled, then check the system clock. VLESS and VMess authentication and secure handshakes depend on correct parameters, and some transports are sensitive to clock drift. Enable automatic date, time, and time-zone settings on the desktop system.

System proxy, browser proxy, and traffic routing

An active node only means that v2rayN has selected an outbound configuration. Whether a webpage uses the proxy also depends on the system proxy and the app’s own network settings. A common mistake is assuming that a successful latency test means the browser will automatically use the local port.

For the first connection, use “System Proxy” → “Automatically Configure System Proxy”. Then refresh the browser page and check whether the logs show the target domain and an outbound record. If no new connection appears at all, the problem is likely between the browser and the local proxy, not with the remote node.

Some browsers read the system proxy, while others with independent settings continue using their own proxy rules. If a proxy was configured manually, check its address, protocol, and port. SOCKS clients commonly connect to 127.0.0.1:10808, while HTTP proxies often use 127.0.0.1:10809; the current v2rayN parameters always take precedence.

Local SOCKS example
Address: 127.0.0.1
Port: 10808

Local HTTP example
Address: 127.0.0.1
Port: 10809

Routing determines whether a connection uses the proxy, connects directly, or is blocked. Right after installation, avoid importing complex rules. Start with the client’s basic rules to verify connectivity, then adjust them to fit your needs. When rules are matched from top to bottom, an overly broad direct rule can capture traffic early and prevent later proxy rules from taking effect.

• Log shows direct: The connection was routed to a direct outbound. Check the domain rules, IP rules, and rule order.
• Log shows proxy but times out: The local proxy received the request. Continue by checking the node, route, and protocol parameters.
• No request in the log: The browser is not using the current system proxy, or the wrong local port was entered.
• Only some websites fail: Check DNS, domain routing, and the browser cache before reinstalling the client.

How to choose a core and when to switch

v2rayN is the management interface; the selected core handles the actual connection. Both Xray and V2Ray cores support common proxy protocols, but their support for newer transport features and parameters differs. After importing nodes from a subscription, the client usually selects a compatible core based on the configuration. Before switching manually, check which protocol the node uses.

If the node uses VLESS + REALITY with the xtls-rprx-vision Flow, choose an Xray core that supports this combination. For standard VMess + WebSocket + TLS, either core will usually work, but follow the parameters supplied by the subscription and the client’s compatibility detection.

The switch path is “Settings” → “Parameter Settings” → “Core Type”. Save the change and select “Restart Service”, then check the core name and version in the logs. Changing the dropdown without restarting may leave the existing process using the old core.

Launch at login, tray operation, and saving settings

Launch at login involves two separate actions: starting the v2rayN main program and restoring the proxy core or system proxy after startup. Enabling only program auto-start does not guarantee that a node will be selected and proxy settings applied after signing in. After the initial setup, restart the computer once for a complete check.

If launch at startup fails on Windows, open the system’s startup apps list and make sure v2rayN is not disabled. Then check whether the program directory was moved. Startup entries usually point to the original program path, so after moving the folder you must turn launch-at-startup off and enable it again.

On macOS, confirm that v2rayN is allowed to launch in the system login items and that its network-related permissions remain enabled. If the program appears only in the Dock or menu bar while webpages still connect directly, check whether the system proxy was restored. After a system update or network change, the proxy settings may need to be applied again.

• Before exiting, confirm that configuration changes have been saved. Do not terminate the core process directly.
• After moving the program directory, set up launch at startup again and check that subscription data is still present.
• Back up the existing configuration directory before updating the client. Afterward, check the core and ports first.
• The tray icon, core process, and system proxy are three separate states; check each one independently.

Work through common issues in this order

When troubleshooting connection problems, a fixed sequence is more effective than repeatedly switching nodes. Check subscription updates, system time, core startup, local port listening, and the system proxy in that order. Only then verify protocol parameters and route status.

Logs can also divide the problem into three segments: browser to local port, local core to node, and node to the target site. No record in the first segment points to the system proxy. A handshake failure in the second points to the time, core, and protocol parameters. Persistent timeouts in the third point to node quality and route conditions.

After completing the initial setup, keep one verified working baseline configuration. Avoid changing the core, ports, DNS, and routing rules at the same time. Change one variable at a time, then use the logs and webpage results to assess the impact. This makes the actual cause much easier to identify.