For your first v2rayN setup, follow this order: check your system architecture → choose where to keep the app and its settings → import nodes → verify the core → configure the system proxy. This guide is for new Windows and macOS users. It explains the difference between launching the app, running the core, and routing app traffic through the proxy. First verify the connection in a browser; consider TUN and advanced routing only after that works.
1. Check your platform, architecture, and runtime before downloading
v2rayN is a desktop client for managing nodes, subscriptions, and routing rules. The core establishes the proxy connection. Downloading the interface does not give you a working node, and opening the app does not guarantee that its bundled core has started correctly. Before installing, choose a package that matches your operating system and processor architecture, and check whether it includes the required runtime and core.
Pre-installation checks for Windows and macOS
Windows
- On Windows, go to Settings → System → About and check System type to distinguish x64 from ARM64.
- Extract the archive fully before launching the app. Don’t run it from an archive utility’s preview window.
- If you’re told that the .NET runtime is missing, check the current release notes for the required component and architecture. Don’t install an arbitrary version based on an old guide.
macOS
- On macOS, open Apple menu → About This Mac and check whether your Mac has Apple silicon or an Intel processor.
- Follow the release instructions to extract the app or move it to Applications. Don’t keep running it from a temporary mounted location.
- If macOS blocks the app, first confirm that you downloaded it from the right source and chose the correct package. Then check the specific message under System Settings → Privacy & Security.
Make sure each system meets the requirements for its package. Check the current download notes to see whether the runtime is included.
On Windows, you can put the portable folder somewhere your user account can write to, such as D:\Tools\v2rayN. This is only an example; you don’t need a D: drive. Avoid protected system folders that require extra permissions, and don’t move the app folder while it’s in use. On macOS, keep in mind that the app itself and its user settings may be stored in different locations.
2. First launch: import a node before connecting
When you first open v2rayN, leave the default routing and DNS settings as they are. There’s no need to change listening ports, enable a virtual network adapter, and replace the core all at once. Tackle one thing at a time so you can tell whether a problem comes from the subscription, node, or local settings. The menu paths below reflect a common Chinese-language interface. Button locations may vary by release, so follow the actual menu labels and field descriptions.
-
Check the app folder
After extracting the app or placing it in Applications, launch v2rayN. Check that settings are saved and remain after you close and reopen the app. If saving fails, check folder permissions first.
-
Add a subscription
Go to Subscription Group → Subscription Group Settings, add a group, enter a name and the full subscription URL, then save. If you don’t have a subscription, use Server → Import share links from clipboard instead. Don’t import a subscription URL as if it were a single node link.
-
Refresh the node list
From the Subscription Group menu, choose the appropriate update command. If you don’t have a working proxy yet, try updating without one. If the list is empty, check the fetch result and parsing messages rather than adding the same group repeatedly.
-
Choose a node
Select a node, then choose Set as active server from the right-click menu. Check the active indicator and logs for core startup errors. Highlighting a row alone may not make that node active.
-
Configure the proxy
From the status bar or tray menu, open System Proxy and choose Automatically configure system proxy. Then use a browser that follows the system proxy to visit a known reachable HTTPS page, and check the logs to confirm that the request reached the core.
Subscription URLs often contain access credentials, so treat them as sensitive account information. When troubleshooting, you can share the status code, error text, and protocol type, but don’t post the full subscription URL, node password, or UUID in a public forum. For more details on importing, see the v2rayN import guide.
3. Choose a core that supports the protocol and security settings
V2Ray, V2Fly, and Xray aren’t different skins for the v2rayN interface. The client converts node settings into a core configuration; the core determines which protocols and transport and security combinations are supported. Technical documentation from Project V, V2Fly, and Xray can help explain these fields, but compatibility depends on the core version bundled with your app and how it’s supported by the client.
| Node type or symptom | Check first | Don’t confuse this with |
|---|---|---|
| VMess node | UUID, transport type, TLS, path, and whether the system clock is correct | VMess support doesn’t guarantee compatibility with every transport combination |
| VLESS + REALITY | Use an Xray core that supports the combination, and check the server’s required fields, such as publicKey, shortId, and serverName | REALITY is a security layer, not a standalone outbound protocol |
| Unknown field warning | Check the subscription format, how the client converts it, and whether the core supports that field | Updating a subscription won’t add missing core capabilities |
| Core exits immediately | Check for configuration parsing errors, an incorrect executable path, permission issues, and port binding errors | Changing system proxy mode won’t fix the connection if the core hasn’t started |
To check the core, open Settings → Parameter Settings and look for the core selection options in your release. Some versions put Core type on a separate page or let you choose a core by protocol; not every version has one global switch. Don’t rely on old screenshots to find settings that have since moved.
- If the node provider specifies a configuration: Follow its core and parameter requirements first.
- If fields disappear after import: Check whether the current client recognizes the share link or subscription format. Don’t just change the protocol name.
- If you just replaced the core: Restart the connection and check the logs to make sure the new file is loaded, not an old process that’s still running.
4. System proxy, routing rules, and TUN: what each one does
“System proxy enabled” only means the operating system’s proxy settings have changed. It doesn’t guarantee that every app will use them. Browsers usually follow system settings, but some command-line tools, games, and apps that manage their own network connections don’t. For your first setup, test an app that follows the system proxy before deciding whether other apps need a proxy address configured separately.
| Setting | What it does | Recommended for first-time setup |
|---|---|---|
| Automatically configure system proxy | Lets apps that follow system proxy settings connect to the local proxy | Start here to test browser access |
| Routing rules | Decide whether requests that reach the core use the proxy, connect directly, or are blocked | Start with the default rules, then adjust them one at a time after the connection works |
| TUN mode | Routes a wider range of traffic through a virtual network adapter and system routing | Once the basic connection works, check permissions, routes, and DNS settings |
Don’t treat “global proxy” as a single universal switch. A routing rule that sends everything through the proxy usually affects only traffic that has reached the core; it can’t force apps that bypass the system proxy to connect. TUN can capture more traffic, but its coverage also depends on routing exclusions and platform support, so it isn’t required for a first launch.
5. Local ports: distinguish the listening port from the server port
The local listening port is where browsers and other apps connect to v2rayN. The server port belongs to the remote node. Changing the local port won’t fix a remote connection refusal. Check the local listener settings under Settings → Parameter Settings, and confirm the actual port shown in the main window. Don’t assume an example in a guide is the default for your version.
If your HTTP or mixed proxy listener is actually at 127.0.0.1:10808, you can enter this address as the app’s HTTP proxy. If that port only offers SOCKS, select SOCKS in the app instead. Some releases provide a mixed listener, while others use separate listeners; check the actual inbound type.
- Port already in use: If the logs show
address already in useor a bind error, first check whether v2rayN is running twice, then see whether another app is using the same listening address and port. - Local use only: Loopback listening is usually the best choice.
127.0.0.1points to the current device; entering it on a phone connects to the phone itself. - LAN access: Allowing LAN connections expands who can reach the listener, so consider firewall rules and access controls. For a first-time setup, don’t open it just to make testing easier.
- After changing a port: Restart the connection and update any apps where you manually configured a proxy. Reapply the system proxy settings too, so they don’t keep using the old port.
6. Troubleshooting: check startup, subscriptions, and connections separately
When troubleshooting, first identify where the failure occurs: the app won’t open, the subscription can’t be fetched, the core won’t start, or only one app can’t connect. Keep your current node and settings, and change one thing at a time. Speed tests are useful as a reference, but they don’t replace checking actual requests and logs. A node appearing in the list or having a display name doesn’t prove the server is currently available.
The window appears and then closes. Should I reinstall?
First check that you downloaded the right platform and architecture, extracted the package fully, and noted any system error shown at launch. If Windows specifically reports a missing runtime, install the required component listed in the release notes. On macOS, check the app security alert first. Don’t repeatedly overwrite the app folder without backing up your settings.
The subscription update timed out. Should I enable “update through proxy”?
Updating through a proxy can help reach the subscription URL only if you already have a working node. If the list is empty and you have no working connection, enabling this option may still time out. Check that the URL is complete and the subscription is still valid, then determine whether the failure is in the network request or content parsing.
The node is selected, but the browser still won’t load pages. What should I check?
Make sure the node is set as the active server, and check the logs for core exits or port binding errors. Then reapply Automatically configure system proxy. If there are no browser requests in the logs, check the proxy listener first. If requests appear but fail, check the node parameters, remote connectivity, and DNS errors.
Why does the browser work when other apps don’t?
First check whether the app follows system proxy settings. If it supports manual proxy configuration, enter the actual local address, port, and protocol type. Consider TUN only if you need to capture traffic from other apps. Don’t disable the firewall outright; traffic that never entered the proxy may have nothing to do with it.
After quitting, regular websites won’t load. What now?
Reopen v2rayN, choose Clear system proxy from the System Proxy menu, then quit normally. On Windows, check Settings → Network & Internet → Proxy. On macOS, check System Settings → Network → your current network service → Details → Proxies. On devices managed by your organization, don’t remove organization settings without permission.
7. First-time setup checklist
Once the basic connection is stable, add custom routing, DNS policies, or TUN one at a time. After enabling each feature, test the browser and your usual apps, and check that networking returns to normal after you quit. Back up subscription groups and custom rules before upgrading. Backups may contain credentials, so store them securely instead of sharing them publicly as screenshots.
- The app and core both start normally, and settings persist after restarting the client.
- The active node is clear, and its protocol, transport, and security settings match the server’s requirements.
- At least one browser that follows the system proxy has successfully loaded a real webpage.
- The local listening address, port, and inbound type have been checked; LAN access hasn’t been enabled unintentionally.
- You know how to clear the system proxy, and regular network access returns after quitting the app.
To review the full setup, start with the client setup guide. For subscription format issues, see the subscription conversion and compatibility guide. Identify which layer is failing before changing your settings; it’s usually easier to find the cause than resetting everything at once.