v2rayN Setup Guide: First-Run Tips for Windows and macOS

At a glance

Before importing a subscription or setting up the system proxy, make sure the app opens, the core starts, and the local port is listening. This guide helps new v2rayN users on Windows and macOS troubleshoot five areas: installation package, runtime, permissions, ports, and proxy routing—so local startup issues aren’t mistaken for node problems.

Understand the app, core, and system proxy

Seeing the v2rayN window doesn’t mean your proxy is ready. The app manages nodes, subscriptions, and settings; the core establishes connections and applies routing rules; the system proxy tells compatible apps to send requests to a local listening port. Check that each component works, in that order.

V2Ray is part of Project V, V2Fly continues the related technology ecosystem, and Xray is another core implementation in this space. v2rayN is a desktop client for managing connection profiles, not a remote server. After importing a VMess or VLESS profile, make sure the selected core supports its protocol and transport settings.

App won’t open: Check the package architecture, runtime requirements, and system security blocks first. There’s no need to keep refreshing subscriptions.
App opens, but the core exits: Check the startup logs, core files, and port conflicts before changing DNS.
Core is running, but websites won’t load: Check the active node, system proxy, and routing rules.
Browser works, but another app doesn’t: Check whether that app follows the system proxy or has its own proxy settings.

Windows and macOS: installation packages and runtime requirements

Choose the right platform from the downloads page. Windows Desktop and WPF are separate UI variants, and WPF is for Windows. On macOS, choose the package for your processor architecture. Don’t apply Windows runtime fixes to macOS.

Before your first run: checks for both platforms

Windows

Open Settings → System → About to check your system type and confirm the package matches your processor architecture.
Follow the installer prompts to complete setup. For an archive, extract all files before running the app—don’t launch it from the archive preview.
Keep portable packages in a fixed folder where your user account can write files. Preserve all bundled files and the original folder structure.
If you see a missing .NET prompt, note the required version, architecture, and runtime name, then install the matching component.

macOS

Open the Apple menu → About This Mac to check whether your Mac has an Apple chip or an Intel processor.
Choose arm64 for Apple silicon and x64 for Intel. Don’t make translation-based execution your first troubleshooting step.
Open the DMG, copy the app to Applications, then launch it from there.
If macOS blocks the app on first launch, verify where the file came from, then check the specific reason in Privacy & Security settings.

Match the package, system architecture, and runtime before setting up connections. You generally don’t need to enable Tun at this stage.

Don’t install a specific version based on an outdated guide

Some release packages include a runtime; others require a specific runtime to be installed on your system. If Windows reports that Microsoft.WindowsDesktop.App is missing, install the .NET Desktop Runtime for the required architecture. The regular .NET Runtime may not meet a WPF app’s requirements. Don’t choose what to install based only on a version number in an old guide.

If there’s no runtime prompt and the app closes immediately after launch, save the full error message. Check your security software’s block history, permissions for the installation folder, and whether the package was fully extracted, then try reinstalling. Don’t leave system protection disabled just to get the app running.

Set up your first connection in five steps

The steps below refer to common options in the Chinese-language UI. Button locations may differ between Desktop and WPF, and menu labels can change between versions. If you can’t find an option, use the settings available in your current UI rather than following screenshot coordinates. For your first connection, test the basic setup without adding complex routing or transparent proxying.

Launch the app

Make sure the window opens and settings can be saved. For a portable package, don’t copy only the main executable. Missing files in the folder can leave the UI working while the core fails to start.
Check the listening port

Go to Settings → Parameter Settings and check the local listening port, listening address, and related inbound options. Note the current port. Leave LAN access disabled for now; if you’re only using the app on this device, use a loopback address.
Add a subscription

In the main window, add a group from Subscription Group, enter the full subscription URL, and save it. Then use the Subscription Group menu to update it. A subscription URL is not the same as an individual share link—don’t enter a webpage URL as a subscription.
Select an active node

Choose a node in the server list and set it as the active server. Check the main window log to make sure the core doesn’t exit immediately. If a file is missing, fix the core files first; if an address is already in use, resolve the port conflict.
Set up the system proxy

Under System Proxy, choose Set system proxy automatically, then use a browser that follows the system proxy to visit a known reachable HTTPS page. If the wording differs between variants, choose the option that actually sets the system proxy, not one that merely keeps existing settings.

Local ports: check the listener, then the proxy target

The port must match in three places: v2rayN’s actual listening settings, the system proxy target, and any manual proxy settings in apps. The two numbers below are examples, not defaults for every version. Check Parameter Settings and the core startup log for the values in use.

10808

Example: local mixed inbound port

10809

Example: separate HTTP port

If your version supports mixed inbound, one port can accept both HTTP and SOCKS requests. With separate inbounds, note each port individually. Don’t enter 10809 just because it appears in an old guide if your setup listens only on 10808. The loopback address is 127.0.0.1, not the remote node address.

Check port usage on Windows

Run the command below in PowerShell or Command Prompt. Replace the example port with the actual value, then check for entries in the listening state and note their process IDs. Entries in other connection states don’t, by themselves, prove that the port is actively listening.

netstat -ano | findstr :10808

Find listening processes on macOS

lsof -nP -iTCP:10808 -sTCP:LISTEN

Something is listening before the client starts: Identify the process first. It may be an old instance or another local service; don’t terminate an unfamiliar system process.
No listener after startup: Check the core log and confirm the core file is executable, the configuration parses, and startup succeeds.
A port conflict is confirmed: Close the duplicate instance or choose an unused port. Reapply the system proxy after changing the port, and update any manual proxy settings in apps.

If websites stop loading after you change the port, first check whether the system proxy still points to the old one. This is a local port mismatch, not a problem with the remote node. Switching nodes repeatedly won’t fix it.

System proxy or Tun: which should you use first?

The system proxy and routing rules operate at different levels. The system proxy determines whether an app sends requests to the client; routing rules determine how requests that reach the core are sent out. So Set system proxy automatically doesn’t mean every destination will use the proxy—the active routing rules still decide the outbound route.

Start with the system proxy

Recommended

First, test apps such as browsers that follow the system proxy. The connection path is shorter, making it easier to tell whether the issue is the port, core, or node. Apps that ignore the system proxy won’t be redirected just because this setting is enabled.

Best for: first-time setup, testing web access, everyday browser use

Enable Tun only when needed

Tun routes traffic through a virtual network interface and typically requires additional permissions, routing, and DNS settings. First confirm that the basic connection works, then enable Tun and test it separately. Follow the permission prompts for your system and client version.

Best for: a verified basic connection when you need to route apps that don’t follow the system proxy

Isolate issues with an explicit proxy

If the example port 10808 actually accepts HTTP or mixed proxy traffic, run the command below. On Windows, use curl.exe to avoid PowerShell environments that interpret curl as another command. On macOS, use curl.

curl.exe --proxy http://127.0.0.1:10808 --connect-timeout 10 -I https://example.com

This command sends the request directly to the local proxy, without relying on whether the browser reads system proxy settings. An HTTP response means this request received a response, but it doesn’t prove that every destination is reachable or that the request used a proxy outbound. If the routing rules send that destination directly, the request may still bypass the proxy. To verify the outbound route, check the request log, matching rule, and outbound tag.

Connection refused immediately: Check the local address, port, and listening status first.
Times out after the local connection is established: Check the node settings, remote reachability, and related logs.
Explicit proxy works, but the browser doesn’t: Check the browser’s own proxy settings and extensions, as well as the system proxy status.

Startup errors and permission prompts: troubleshoot the specific message

When troubleshooting a first launch, the full error message is more useful than simply saying the app won’t open. Note whether the error occurs when launching the app, starting the core, or enabling Tun. Each step requires different permissions, so running everything as an administrator isn’t a one-size-fits-all fix.

Windows says a runtime is missing after launch. Which one should I install?

Note the framework name, version, and architecture shown in the prompt. If it asks for Windows Desktop Runtime, install the matching desktop runtime, not just the regular runtime. Restart the client after installation. If it still fails, check that you didn’t install a component for a different processor architecture.

macOS says it can’t verify the developer. How do I open the app?

After confirming the download source and app identity, go to System Settings → Privacy & Security and read the explanation for this block. If macOS offers Open Anyway, follow the prompt to confirm. On older systems, the setting may be under System Preferences. Don’t disable security checks globally to resolve a prompt for one app.

The app opens, but says the core can’t be found. Why?

Check whether the package includes the required core, then make sure the original folder structure hasn’t been changed and that security software hasn’t quarantined the file. Restore the matching files using the core update feature in your version or a complete release package. Don’t copy a core from another platform.

Tun asks for elevated permissions. Does that mean installation failed?

These are separate issues. Virtual interfaces and system route changes typically require additional permissions. Turn off Tun and test system proxy mode first. If you need traffic interception, grant the required permissions as prompted by your client version. On a managed device, follow your organization’s device policies.

Exit and verify: don’t leave a broken proxy behind

After your first successful connection, there’s no need to add complex rules right away. Test three things: restart the client, switch the active node, and exit normally. Confirm that settings persist, the port stays the same, and network access is restored after exit. Force-quitting the process or an unexpected shutdown can leave the system proxy pointing to a local service that’s no longer running.

After restarting: Check that the subscription group and active node are still there, and that the log isn’t repeating startup errors.
While connected: Confirm the local port is listening, the browser gets a response, and the request follows the expected route.
Before exiting normally: Under System Proxy, choose Clear system proxy, then exit the client. If you use another network management setup, restore its original settings.
After an unexpected exit: On Windows, check Settings → Network & Internet → Proxy. On macOS, check System Settings → Network → your current network service → Details → Proxies. Remove only the local proxy settings changed by this test; don’t overwrite settings required by your organization’s network.

These checks take you beyond simply installing the app and help ensure the basic connection works reliably. If one website fails later, troubleshoot routing, DNS, and node settings one at a time. For the full setup sequence, see the Getting Started guide. To troubleshoot by symptom, consult the Troubleshooting guide.