Nov 15, 2026 · Getting Started · About 8 min read

v2rayN First-Time Setup for Windows and macOS: Installation, Configuration, and Common Issues

Learn how to install v2rayN on Windows or macOS, import a subscription, choose a core, and configure launch at login—plus how to avoid common setup issues.

At a glance

Setting up v2rayN 7.x for the first time? Choose the right package for your operating system and processor architecture, then import your configuration, activate a node, and test the local proxy. Installation and permission settings differ between Windows and macOS, but the connection checks are the same. Once the app can access a site through the proxy, configure it to launch at login. If something goes wrong, troubleshoot installation, subscriptions, cores, and the app in turn—there's no need to reinstall straight away.

Choose a package and launch v2rayN for the first time

Opening the main window only confirms that the client interface has started; it doesn't mean the core that handles connections is running. When downloading, check the operating system, processor architecture, and whether the package includes a core. For a first-time setup, choose a release that clearly includes the core you need so you don't discover missing executable files after importing nodes.

Choose a package for Windows

Check your architecture
Settings → System → About → System type
Package label
Choose x64 for an x64-based processor; on ARM devices, select the arm64 package that matches your system
Archive
Extract all files to a writable folder in your user account that you won't move later
First launch
For an archive, run v2rayN.exe from the extracted folder; for an installer, follow the prompts

Don't double-click the main program in your archive utility's preview window. Nearby core files may not be extracted with it.

Choose a package for macOS

Check your architecture
Apple menu → About This Mac; check Chip or Processor
Package label
Choose arm64 for Apple silicon and x64 for Intel processors
App location
Extract the package or open the disk image as instructed, then move the app to Applications
First launch
Open the app from Applications; don't use the disk image as a permanent location

Open the app manually once after installation. This ensures login items point to the app in its permanent location, not a temporarily mounted disk image.

  • Windows says a runtime is missing: Check the runtime name and major version in the error, then compare them with the release notes. If your package depends on a system runtime, install the matching .NET Desktop Runtime for your processor architecture as prompted. Administrator privileges cannot replace a missing runtime.
  • macOS says the developer cannot be verified: First confirm the package source and architecture. If macOS shows a developer verification warning and you trust the app, try opening it once, then check System Settings → Privacy & Security for an Open Anyway option. If macOS says the app will damage your computer, don't run it or disable system-wide security protections.

Importing a subscription: save, update, then activate

A subscription URL retrieves a set of nodes; saving the URL doesn't create a working connection by itself. The steps below use the Chinese interface in v2rayN 7.x and describe menu functions; wording may vary slightly between minor versions. If you have a single-node share link beginning with vmess:// or vless://, use the clipboard import function for servers instead of entering it as a subscription URL.

  1. Create a subscription group

    Open Subscription Group → Subscription Group Settings and add an entry. Enter a recognizable name and the full subscription URL, then save and return to the main window. Subscription URLs may contain access tokens; don't share them in public screenshots or logs.

  2. Update the subscription list

    Select the new group, then choose Update Current Subscription (without proxy) from the Subscription Group menu. On a fresh install, you don't have a working node yet, so don't choose the option to update through a proxy. When the update finishes, check that nodes appear in the group—not just that the group was created.

  3. Set an active node

    Select a node you know works, right-click it, and choose Set as Active Server. Clicking a row only selects it; it doesn't switch the connection. After switching, check the active entry in the main window and the logs to make sure the core hasn't exited.

  4. Test the app's connection

    First test the local proxy port. Then, from the system tray or menu bar icon, open the System Proxy menu and choose Automatically Configure System Proxy. Disable any browser-specific proxy rules that override system settings, open a known-accessible HTTPS site, and check that it loads.

Choose a core: test the current setup before changing mappings

A node stores connection settings such as protocol, remote address, and transport; the core applies them. Go to Settings → Parameter Settings → Core Type (called Core Type Settings in some versions) to see which cores are available for built-in node protocols. This setting doesn't convert a VMess node to VLESS. Custom nodes with complete configurations may not follow these general guidelines.

Keep the node's current core

Recommended

Keep the current protocol mapping, activate the node, and check the logs first. If the server specifies VLESS + REALITY and the current Xray loads the configuration correctly, don't change the core, transport, and security settings all at once just for troubleshooting.

Best for: first-time setup and standard subscriptions you can import

Change the core to match the server

Choose an installed core that supports the required combination only if the server explicitly specifies a compatibility requirement or the logs show that the current core doesn't recognize a configuration field. After saving, reactivate the same node and compare the logs. Don't switch servers at the same time, or you won't know which change made a difference.

Best for: migrating a known configuration or troubleshooting a specific compatibility issue

If the logs say the core file can't be found, first check the package contents and platform architecture. If the core starts but the connection logs show a TLS or authentication error, check that the address, server name, and authentication settings in the subscription all come from the same configuration. Don't disable certificate verification to work around mismatched settings.

Test the local listener and system proxy separately

Check the local listening port in Settings → Parameter Settings. The example below uses the mixed inbound port 10808, which accepts this test as an HTTP proxy. If the interface shows separate SOCKS and HTTP ports, use the HTTP inbound port in the command. You can leave the system proxy disabled for now because the command connects directly to the local proxy.

curl -I --max-time 10 --proxy http://127.0.0.1:10808 https://example.com/

In Windows PowerShell, you can replace the command's opening curl with curl.exe. The command waits up to 10 seconds. Check the final HTTP status line returned by the destination site, not just the 200 Connection established message that may appear when the proxy tunnel is created. This command checks the route from this app to this destination; it isn't a speed test.

What you seeWhat to check next
Connection to 127.0.0.1:10808 refusedMake sure the core is still running and that the port and inbound type are correct. Then check the logs for listener errors or a port conflict.
Tunnel established, followed by a timeout or TLS errorThe local port accepted the request. Check the core logs for the active outbound, server reachability, and TLS settings; don't start by changing browser settings.
The command gets a response from the destination, but the browser failsCheck whether the browser uses the system proxy or has an extension or built-in proxy setting that overrides it. Restart the browser and test the same URL again.

The system proxy directs apps that honor system settings to the local listener. Routing rules determine whether connections reaching the core use a proxy outbound or connect directly. A successful command only confirms that the request passed through the local inbound and received a response. To confirm that it used a proxy outbound, check the active routing rules and available connection logs; a page loading on its own isn't proof.

Launch at login and common issues

Set up launch at login after the browser test succeeds. The app usually starts when you sign in, not before anyone logs in. Launching the client and restoring the system proxy are separate settings, so test each one after configuration.

  • Windows: Go to Settings → Parameter Settings and check the Launch at startup option. Set the program's permanent folder first. If you later move the folder containing the portable version, update the startup setting so it doesn't point to the old location.
  • macOS: In System Settings → General → Login Items, add v2rayN from Applications to the Open at Login list. Some macOS versions call this page Login Items & Extensions. If the client is already configured to launch at login, don't add the same app again.
  • Verify after signing out and back in: Confirm that the client opens, then check the active node, core logs, and system proxy status. If you stop using the app, clear the system proxy before quitting so other apps don't keep sending requests to a closed local port.

Why is my subscription group empty even though it has a name?

Select the group, choose Update Current Subscription (without proxy), and check the update log. If you see HTTP 401 or 403, make sure the URL is complete and the access token is still valid. If the request times out, first check whether your computer can reach the subscription service. Only try updating through a proxy if you already have a working proxy.

Why can I measure node latency but still not open a webpage?

A latency result doesn't mean your browser is using that node. First confirm that it's the active server, then run the command with the local proxy explicitly specified and test the same destination. If the command succeeds but the browser fails, check the browser's proxy settings before sorting by latency and trying another node.

Why does the proxy keep working after I close the window?

Check whether the v2rayN icon is still in the system tray or menu bar. If close-to-tray behavior is enabled, closing the window doesn't quit the client. To stop it, clear the system proxy from its menu, then choose Exit from the client menu.

The client launched at sign-in, so why isn't my terminal using the proxy?

Many command-line tools don't inherit the desktop system proxy settings. First, test with the tool's proxy option—for example, use curl --proxy as shown above to specify the local inbound. Only configure the tool's supported proxy options or environment variables if you need them long term. There's no need to change global settings just to proxy one command.

Client downloads