v2rayN First-Time Installation and Setup for Windows and macOS

At a Glance

For first-time v2rayN users on Windows or macOS. Set things up in order: choose the right package and architecture, check runtime requirements, select a core, import a subscription, configure local ports and system proxy. First, get one server connected; then adjust routing and startup options. Ports 10808 and 10809 are examples, not universal defaults. Check the client settings and startup logs for the actual values.

1. Choose the Right Package: Check Your OS, Architecture, and App Type

v2rayN is a desktop client for managing servers, running proxy cores, and configuring local proxy endpoints. Seeing the main window only confirms that the app has launched; check the core files, server settings, and system proxy separately. For a first-time installation, choose the right platform on the client download page. Keep the package type and architecture details handy to make troubleshooting easier.

What to Check	Windows	macOS
Operating System and Architecture	Go to Settings → System → About and check “System type.” Don’t confuse x64 with ARM64.	Open the Apple menu → About This Mac. Choose arm64 for Apple silicon and x64 for an Intel processor.
App Type	Use the download page to distinguish the desktop version from the classic WPF version. The WPF interface is for Windows only.	Choose the macOS desktop version; Windows executables won’t run on macOS.
Runtime Requirements	Packages that depend on a framework need a compatible .NET runtime. Self-contained packages usually include the required runtime.	Check the package notes to see whether an additional runtime is needed. Don’t follow Windows Desktop Runtime installation steps on macOS.
Version Details	Record the client version, package type, and architecture—not just the core version shown in the interface.	Also note the OS version and processor type to help distinguish compatibility issues from architecture problems.

Don’t install multiple runtime versions just because you see “.NET.” A missing-runtime prompt usually names the framework, required version, and architecture. For example, if it reports that Microsoft.WindowsDesktop.App is missing, check for the matching .NET Desktop Runtime—not just the base Runtime or the developer SDK. The required major version depends on the client package; follow its notes and the error message.

2. First Launch: Choose a Folder, App Location, and Permissions

On Windows, fully extract the archive before launching the app. Opening the executable inside an archive may extract only a temporary file, preventing the core, resources, or configuration from loading correctly. You can place the extracted app in a permanent, user-writable folder such as D:\Tools\v2rayN. The path is just an example; the important thing is that the folder remains in place and your account can save settings there.

Check the Package

On the download page, confirm the OS, processor architecture, and package type. On Windows, use the built-in “Extract all” option to unpack the full archive. If you have an installer, follow its setup wizard instead of applying the extracted-package folder instructions.
Choose a Permanent Location

Keep the full folder structure for the extracted Windows version. On macOS, if the download includes a disk image, open it and copy the app to Applications. Don’t run it long-term from the temporarily mounted image.
Complete the First Launch

On Windows, start the app as a standard user first. On macOS, if a warning says the developer can’t be verified, confirm the download source, then follow the system prompts in System Settings → Privacy & Security to review the option to open it. Don’t disable system security checks entirely.
Check the Startup Logs

Open the log pane in the main window and confirm that settings can be saved and the core starts. If you see missing files, permission errors, or an architecture mismatch, fix that issue before importing a subscription.

3. Choose a Core: Match Xray or V2Fly to Your Server

The client and core are separate programs. v2rayN manages the interface and settings; the core handles the proxy connection. It’s normal for their version numbers to differ, so don’t replace files just to make the numbers match. For a first-time setup, keep the core configuration provided with the package. If you need a specific protocol, check Settings → Parameter Settings and the Core type options available in your version.

Xray Core

Recommended

A good first choice when your server requires Xray features. Configurations such as VLESS + REALITY need a compatible core; the protocol name alone doesn’t guarantee that every core can run them. Supported fields also depend on the core version.

Best for: servers that specifically require Xray or use REALITY.

V2Fly Core

Use this for configurations supported by V2Fly, such as VMess servers that meet its requirements. Base the choice on the options included with your v2rayN package and the server’s requirements; V2Fly isn’t a drop-in replacement for every Xray feature.

Best for: setups where the server explicitly provides a V2Fly-compatible configuration.

Core type settings may be organized differently across versions, with some versions assigning cores by protocol. Confirm which core the selected server actually uses; seeing a core name in the settings window isn’t enough. If the logs report an unsupported field or a configuration parsing error, check the server requirements and core version. Don’t randomly change encryption, transport, or TLS settings.

Missing files: Extract the package again in full and check your system’s security history to see whether the core file was quarantined. Don’t download individual files from untrusted sources.
Architecture mismatch: The app and core must both use an architecture supported by your system. The main window opening doesn’t guarantee that the bundled core can run.
Core won’t start: Save the first core error and the surrounding log entries. Subsequent connection failures may simply be a result of the core not starting.

4. Import a Subscription: Select a Server and Test the Connection

Installing the client doesn’t give you a server automatically. Your service provider supplies the subscription URL, which usually contains access credentials. An account login page, plan details page, or individual server share link is not a subscription URL. When copying it, make sure the entire address is intact, with no line breaks, curly quotes, or extra spaces.

In the v2rayN main window, open Subscription Group → Subscription Group Settings. Add a group, enter a recognizable name and the subscription URL, then save.
Return to the Subscription Group menu and select Update All Subscriptions (without proxy). If you don’t have a working server yet, try updating directly first.
Check that servers appear in the list. If the subscription URL is only accessible through a proxy, you’ll need another working connection first; then select Update All Subscriptions (through proxy). This option can’t create your first connection from scratch.
Select a server in the list, then choose Set as Active Server from the right-click menu. Confirm that the active server has changed and check the logs for startup errors.
Use the client’s connection test as an initial check, then configure the system proxy. A successful latency test doesn’t mean your browser is using that server.

5. Local Listening Ports: Match the Client and System Settings

The local listening address is the endpoint your apps connect to through v2rayN, not the remote server address. Check the local listener settings under Settings → Parameter Settings. If the client asks you to restart the core after saving, do so and verify the listening port in the logs. The examples below show two different configurations; don’t assume both are defaults in your version.

Example: Single Mixed Listener

Listen Address: 127.0.0.1
Mixed Port: 10808
Protocol Entry: HTTP and SOCKS, handled by a mixed inbound
System Proxy: Points to 127.0.0.1:10808

Use this only if your version explicitly supports a mixed inbound. Check the logs to confirm that it accepts the protocols you need.

Example: Separate Listeners

Listen Address: 127.0.0.1
SOCKS Port: 10808
HTTP Port: 10809
System Proxy: HTTP proxy points to 127.0.0.1:10809

Use this setup when HTTP and SOCKS inbounds are configured separately. Don’t enter a SOCKS-only port in the HTTP proxy field.

For your first setup, keep the loopback address 127.0.0.1. Enabling “Allow connections from the LAN” changes who can access the proxy and involves firewall and access-control considerations; it isn’t a general fix for web pages that won’t load on your own device. The port in the system proxy, any manually configured app proxy, and the listening port in the core logs must all match.

How to Check for a Port Conflict

If the logs show address already in use, first check whether v2rayN is already running in another window. These examples show how to check from Windows Command Prompt and the macOS Terminal; replace the port number if you’re using a different one.

netstat -ano | findstr ":10808"

lsof -nP -iTCP:10808 -sTCP:LISTEN

On Windows, check the local address and listening state. You can look up the PID in the last column under Details in Task Manager. Confirm which app owns the process before closing a duplicate instance or changing the local port. Don’t terminate an unfamiliar process just because you recognize the number. If you change the port, update the system proxy and any manually configured proxy settings too.

6. System Proxy and Routing: Check Each Setting Separately

The system proxy tells apps that follow OS proxy settings where to send requests. Routing rules decide whether requests reaching the core go direct, through a proxy, or get blocked. Selecting Global proxy doesn’t make every app follow the system proxy, and choosing Auto-configure system proxy doesn’t mean every request handled by the core will go through a remote server.

Setting or Check	First-Time Setup	What to Check
v2rayN System Proxy	Select Auto-configure system proxy to have the client set the local proxy endpoint.	The system proxy address and port should match the active HTTP or mixed listener.
Windows Settings → Network & internet → Proxy	Check the manual proxy settings and remove any outdated address left by another tool.	When using a local endpoint, the address and port should match the actual local listener.
macOS System Settings → Network → Current network service → Details → Proxies	Check the Wi-Fi or Ethernet service you’re currently using, not a disconnected service.	The web proxy and secure web proxy settings should match the values set by the client.
v2rayN Routing	Keep the built-in routing rules for your first setup. For troubleshooting, temporarily select a clearly defined proxy rule to compare results.	Use the logs to check the outbound route for the target request; don’t rely on the mode name in the toolbar alone.

Test the connection: Open a known-accessible HTTPS page and check whether the core logs show the corresponding connection. If the logs don’t provide enough detail, temporarily increase the log level and restore it after testing.
App differences: Some browsers have their own proxy settings, while some command-line tools read only environment variables. These apps may not follow the system proxy.
Exit in order: Before closing v2rayN, select Clear system proxy under System Proxy. If the app closes unexpectedly and leaves old settings behind, restore them manually in your OS proxy settings.

Once the basic connection works, enable startup on boot, automatic subscription updates, or TUN only if needed. On macOS, check the proxy settings for the current network service if the proxy behaves differently after switching services. On Windows, if settings revert immediately after being applied, check for another proxy app, management policy, or security tool controlling them.

7. Common First-Install Issues: Troubleshoot by Where They Occur

Nothing happens after double-clicking, or the app immediately crashes. What should I check first?

First, check Task Manager or Activity Monitor to see whether the app is already running in the background. If there’s no process, check that the archive was fully extracted, the architecture is correct, and there are no runtime warnings. On Windows, you can launch the main app from a terminal to view its output. If a dependency is missing, match the framework and architecture named in the prompt. Don’t change server settings first.

macOS says the app can’t be opened. Can I bypass the warning?

First, distinguish a developer verification warning from an OS compatibility issue or a damaged app. Follow the system process under Privacy & Security for a developer warning. If the app is reported as damaged, download the package again for the right architecture and check the release notes for system requirements. Don’t copy bulk commands to bypass security from an untrusted source.

The server responds to a latency test, but web pages still won’t load. Why?

Check three things: whether the core started, whether the local port is listening, and whether the browser follows the system proxy. Compare the system proxy port with the startup logs character by character. If requests reach the core, check for server handshake, DNS, and routing errors. A single latency result doesn’t confirm that web browsing works.

I selected auto-configure, but the system proxy didn’t change. What now?

Reopen your OS proxy settings and check the current values. On macOS, make sure you’ve selected the network service you’re currently using. Temporarily quit other proxy management tools and try again. Organization-managed devices may restrict changes; follow your device management process instead of repeatedly elevating permissions or changing system policies.

After closing v2rayN, even pages that used to load won’t open. Why?

A common cause is that the system proxy still points to a local port that’s no longer listening. Restart the client and select Clear system proxy, or disable the corresponding manual proxy in your system network settings. Restore a direct connection before deciding whether to reopen the client; reinstalling the whole app shouldn’t be your first step.

What to Include When Asking for Help

Your OS version, processor architecture, v2rayN version, and package type, such as the desktop or WPF version.
The core and its version, actual local listening port, system proxy mode, and whether TUN is enabled.
Where the error occurred: launching the interface, starting the core, updating the subscription, or opening a web page. Include the first relevant error and when it occurred.
Hide your subscription URL, server credentials, UUID, and password before sharing. Screenshots should show setting names and error messages, not a complete server configuration.

Your first setup is complete when the client saves its settings, the core starts normally, the local endpoint matches the system proxy, and a web page loads successfully. Once all four checks pass, adjust routing and automation options one at a time. That way, if something breaks, you can return to the last working setup.