v2rayN First-Time Setup: Install on Windows and macOS, Choose a Core, Fix Common Issues

At a Glance

This guide is for Windows and macOS users setting up v2rayN for the first time. Follow these steps in order: choose a download, move it to a stable location, verify that the core starts, import your configuration, and set up the system proxy. Start with a standard proxy connection before trying TUN mode. If startup fails, use the logs, file paths, and local listening port to narrow down the cause instead of assuming the server is at fault.

1. Choose the Right Download for Your OS and Processor

v2rayN provides the client interface; the core handles proxy connections. Launching the main program does not mean the core is installed or your configuration is ready to use. Keep the download's original folder structure during setup. Don't copy only the main program to your desktop or mix files from different releases.

On Windows, check System type under Settings → System → About. On macOS, check Chip or Processor under Apple menu → About This Mac. Apple silicon uses ARM64; Intel processors use x64. Don't treat an x64 package as a native ARM64 build on Windows ARM devices. Whether it runs depends on your system's compatibility support.

Windows Desktop Edition

Recommended

For a first-time setup, start with the Windows desktop download on the download page. Follow the page's instructions to choose between the installer and the archive: run the installer and follow its prompts, or fully extract the archive before launching the app.

Best for: Windows users setting up v2rayN for the first time or looking for a cross-platform desktop interface.

Windows WPF Edition

Keeps the classic Windows interface. Choose this if you're already familiar with it. Don't overwrite the WPF edition's settings with files from the desktop edition; back up your data before migrating.

Best for: Users familiar with the classic Windows menus and window layout.

macOS Desktop Edition

Choose ARM64 or x64 to match your processor. After downloading the DMG, open it and drag the app to Applications. Launch it from there rather than running it from the mounted disk image.

Best for: Mac users with Apple silicon or an Intel processor.

2. Extract and Launch on Windows: Use a Stable Folder and Keep All Files

These steps apply to archive downloads. If you downloaded an installer, install the app first—don't handle it as an archive. You don't need to enable TUN for a standard system proxy, and running as administrator is not a one-size-fits-all fix for startup problems.

Extract the Full Archive

Right-click the archive and choose Extract All. Extract it to a stable folder you can write to, such as D:\Tools\v2rayN. Don't launch the main program from the archive preview; temporary extraction can separate the configuration from the core files.
Launch the Main Program

Open the extracted folder and run v2rayN.exe. Keep its dependencies and subfolders alongside it. To add a desktop shortcut, create one instead of moving the executable.
Check Runtime Requirements

If a prompt asks you to install the .NET Desktop Runtime, check which version and architecture it requires. Runtime files vary between releases, so don't install a different architecture just because you see “.NET” in the message.
Import a Subscription

In the main window, open Subscription Group → Subscription Group Settings, add a group, and enter its URL. Save it, then choose Update from the Subscription Group menu. Depending on the interface version, the button may say Add or show a + sign. Enter the URL in the subscription group field, not the single-server editor.
Select a Server

After updating, select a server from the list and choose Set as active server from the right-click menu. Check the main window's log for errors such as “failed to start process,” “file not found,” or port binding failures before setting up the system proxy.

3. Allow the App to Open on macOS: Separate App Warnings from Core Errors

A macOS warning when you first open the app is different from a proxy core failing to start. The first concerns the app itself; the second usually points to a specific file in the app log. If the window opens but clicking Connect does nothing, check the logs instead of repeatedly removing and reinstalling the app in Applications.

Move the app first: Put it in Applications, eject the downloaded disk image, then open the app from Finder. If you downloaded an archive, extract it to a stable location first. Don't run the app from the download preview.
Handle the first-launch warning: After confirming where the app came from, Control-click it in Finder and choose Open. If macOS still blocks it, check the relevant message under System Settings → Privacy & Security. Choose Open Anyway only if you're sure the prompt is for this app. The exact buttons may vary by macOS version.
Check core errors in the logs: permission denied points to execution or access permissions; bad CPU type in executable points to an architecture mismatch. These errors need different fixes.
Grant permissions only when needed: If changing the system proxy prompts for authorization, verify the app's name before proceeding. You don't need to grant Full Disk Access just to troubleshoot a standard proxy connection.

Don't copy terminal commands that recursively remove security attributes from an entire folder, and don't assume every “app is damaged” warning means you need to bypass system protections. First download the release for the correct architecture and review the system warning. Managed devices may also be restricted by organizational policies; check with your administrator.

4. Find the Core Files: Follow the Startup Path in the Logs

v2rayN manages servers and settings; cores such as Xray and V2Fly process the corresponding configuration. Protocols and cores are different things. VLESS with REALITY requires a core that supports that combination. The fact that two cores handle some of the same proxy protocols doesn't mean they're interchangeable.

Windows Checks

Main program: v2rayN.exe
Example core: The Xray executable is commonly named xray.exe
Typical location: The release's bin folder and its core subfolders
Use this to verify the path: The file path the log actually tries to launch

Folder structures vary between releases. Don't create a folder with the same name based on an old guide.

macOS Checks

App location: App bundle in /Applications
Example core: The Xray executable usually has no .exe extension
Match the architecture: ARM64 or x64, matching the release you downloaded
Use these errors to diagnose: Execution path, permission errors, and architecture errors in the logs

App resources and user data may be stored separately. Check the current release and startup logs.

To check which core is selected, open Settings → Parameter Settings and review the core options available in your version. Some interfaces label this setting Core Type; others let you choose a core per protocol. Don't keep switching cores if there are no errors. If the logs explicitly say a core is missing, reinstall the correct release or use the client's built-in core updater. Don't rename an arbitrary executable and drop it into the folder.

File not found: Check the path in the logs. Confirm the archive was fully extracted, the file wasn't quarantined by security software, and an update wasn't interrupted.
Configuration parse error: Check the field named in the error and confirm the server protocol is supported by the selected core. Toggling the system proxy won't fix this.
Missing data files: If routing rules reference geoip.dat or geosite.dat, make sure those files are in the resource location used by the core.

5. System Proxy and Ports: Verify the Local Connection First

Once the core starts, open System Proxy in the main window and choose Set system proxy. The system proxy determines whether apps that follow system settings send requests through the local proxy. Routing rules determine whether requests are proxied or sent directly after they reach the core. Choosing Global routing won't automatically route traffic from every app, and it doesn't replace the system proxy setting.

Check the local listening port under Settings → Parameter Settings; it may be on the Basic Settings tab. The example 127.0.0.1:10808 below is for troubleshooting only, not a guaranteed default. Before running a test, replace it with the actual port shown in the interface and confirm it accepts HTTP or mixed proxy traffic.

Check Whether a Process Is Listening

Run the first command in PowerShell on Windows and the second in Terminal on macOS. A listening entry only tells you that a process is using the port; verify that the process belongs to the core you just started.

# Windows PowerShell
Get-NetTCPConnection -State Listen -LocalPort 10808 |
  Select-Object LocalAddress, LocalPort, OwningProcess

# macOS Terminal
lsof -nP -iTCP:10808 -sTCP:LISTEN

No listening entry: Check the client logs for a core that didn't start, an unsaved port setting, or a failed configuration.
Log says address already in use: Close any duplicate client instances, then identify the process using the port. Don't terminate an unfamiliar system process until you know what it is.
After changing the listening port: Restart the core and reapply the system proxy settings so they don't keep pointing to the old port.

Test the Proxy Explicitly

Use the request below to check whether the HTTP proxy endpoint accepts connections. Use curl.exe on Windows and curl on macOS. The destination is just a connectivity example: if routing sends it directly, a successful response still doesn't prove the remote proxy server is working.

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

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

6. First-Time Setup FAQ and Restoring Your Settings

Nothing happens when I double-click. Did installation fail?

Check the taskbar notification area or macOS menu bar to see whether the app is already running. On Windows, check Task Manager for duplicate processes. If a runtime prompt appears, follow its instructions. Repeatedly double-clicking can start multiple instances, causing the later core to run into a port conflict.

A subscription update failed. Should I reinstall?

Not yet. Make sure you entered a full subscription URL, not a single vmess:// or vless:// share link. Import individual links using the clipboard import option. Then check your system date and time, and use the logs to distinguish a timeout from a certificate error or server rejection. Hide subscription URLs and credentials before sharing troubleshooting screenshots.

The speed test works, but websites won't load. Why?

A speed test doesn't mean your browser is using the system proxy. Check the core logs, local listener, system proxy address, and browser extensions in that order. If a request with an explicitly specified proxy works but the browser doesn't, check the browser's proxy settings first. If both fail, check the server, routing, and DNS errors.

After closing v2rayN, I can't open regular websites. What should I do?

Reopen the client, choose Clear system proxy from the System Proxy menu, then exit normally. On Windows, check Settings → Network & Internet → Proxy for a manual proxy. On macOS, check System Settings → Network → your current network → Details → Proxies for leftover settings. Note the original settings before changing them, and don't remove a proxy configured by your organization without checking first.

After setup, keep track of three things: the program's actual folder, the active core, and the local listening address and port. Start troubleshooting with these details and the logs, changing one setting at a time. Back up the client's configuration data before upgrading. Never post a full configuration containing subscription credentials in a public forum.