v2rayN First-Time Setup: Windows and macOS Installation Guide

At a glance

For desktop users launching v2rayN for the first time, or who have imported nodes but still can’t access the internet. Follow the steps in order: package and install location, core startup, subscription import, system proxy, connection test, and startup settings. First, get one node working in a browser; consider TUN and custom routing later. The 10808 and 10809 values are example ports for identifying settings—always use the values shown in your client.

1. Choose the right package for your OS and processor

v2rayN is a desktop client for managing nodes, subscriptions, cores, and system proxy settings. The selected core, such as Xray-core or sing-box, handles the actual connection. Downloading the client does not provide a working node; you’ll need a subscription URL or node details from a trusted source.

Start on the download page by selecting your operating system and processor architecture. On Windows, check Settings → System → About for your system type. On macOS, open About This Mac from the Apple menu to check your chip or processor. Apple silicon Macs generally need the arm64 package; Intel Macs need x64. Don’t choose a package based on file size alone.

Check	Windows	macOS
Install location	Fully extract portable packages to a writable folder in your user account, such as `D:\Tools\v2rayN`	Install application packages in Applications as instructed. Don’t run them from a disk image long-term.
How to launch	Run the main program from the extracted folder; don’t open it from inside the archive.	Launch the app from its installed location, using a standard user account first.
Dependencies	If you’re prompted to install a runtime, install the version and architecture specified in the error message.	Windows desktop runtimes don’t apply here. Check that you have the macOS package for your chip architecture.
Saving data	Avoid temporary, read-only, and automatically cleaned folders.	Keep the app’s data folder. Before moving the app, check where its configuration is stored.

2. First launch: make sure settings save and the core runs

On first launch, leave DNS, routing, TUN, and port settings alone. Keep the defaults and check the main window’s logs. Seeing the interface only confirms that the app launched; after selecting a node, verify that the core starts successfully without port conflicts or missing-file errors.

Extract everything

On Windows, extract every file and subfolder from the archive. On macOS, follow the package instructions. Don’t copy only the main program or mix core folders from different versions.
Check the settings

Go to Settings → Parameter Settings and check the local listening ports and options for the selected core. Subsection names may vary by platform and version. Note the values shown in your client rather than copying them from screenshots of another version.
Import a node

Manage subscriptions from the Subscription Group menu on the main screen, or add an individual node using the clipboard import option in the Servers menu. After importing, check the protocol, address, port, and transport settings.
Set an active node

Select a node in the list and choose Set as Active Server from the context menu. Then check the logs to confirm the selected core started successfully; a highlighted node alone isn’t enough.
Save and relaunch

Leave startup settings disabled for now. Exit the client normally, then reopen it and check that your subscriptions, nodes, and settings are still there. If anything is missing, check write permissions and the data folder location.

If the logs say the core executable can’t be found, check whether the package includes that core, whether its files are intact, and whether security software quarantined them. Changing the “core type” setting won’t put missing files in place. Don’t restore blocked files until you’ve verified their source.

3. Subscriptions and nodes: a successful import isn’t a connection

A subscription is a way to retrieve node configurations, not a proxy listening address. A full subscription URL may contain an access token; keep it private like a password, and don’t post it in public comments or show it in full in troubleshooting screenshots. You can rename nodes, but their protocol and transport settings must match the server.

Add a group: Go to Subscription Group → Subscription Group Settings, add an entry, fill in a name and subscription URL, then save. Menu labels may vary; use the subscription management option in your version.
Update the subscription: Return to Subscription Group and choose the update option. If you don’t have a working proxy yet, try updating directly. Use a proxy only if you already have a working node and a direct update fails.
Check the results: The node list should show individual server entries. If it’s empty, first check whether the subscription request succeeded, then confirm that the response uses a format supported by the client.
Select an active node: Set a node as the active server, then test the connection. Seeing dozens of nodes in the list doesn’t mean one is selected for outgoing traffic.

VMess and VLESS are proxy protocols; WebSocket is a transport; TLS and REALITY are security-related settings. They aren’t interchangeable. When entering a node manually, check the server address, port, user ID, transport, and security settings. For example, the WebSocket path /ws is not the same as /, and the TLS server name may differ from the connection address.

4. Local ports: distinguish the browser proxy from the server port

The remote server port and the local proxy port are two different things. A node using 443 doesn’t mean you should set your browser’s local proxy to 443. Your browser connects to a local listener, and the core connects to the remote server. These examples show two common configurations; you don’t need to enable both.

Example: mixed listener

Local address: 127.0.0.1
Example ports: 10808
Supported protocols: HTTP and SOCKS, depending on the inbound configuration
When to use: The client explicitly identifies this port as a mixed listener

HTTP and SOCKS apps can share a port only when it’s confirmed to be a mixed port.

Example: separate listeners

Local address: 127.0.0.1
SOCKS port: 10808
HTTP port: 10809
When to use: Both listeners are enabled in the current configuration

Older guides often use these separate ports. Check your current client before entering them.

If the logs show address already in use, another process is using the listening address or port. Close any duplicate client instances, then check for other proxy processes. If you need to change the port, update the system proxy and any manual proxy settings in your apps too. Changing it in the client alone leaves those apps pointing to the old port.

For use on one device, keep the listener on the loopback address. You don’t need to enable LAN access to get started.
127.0.0.1 refers to the current device. Entering this address on another device won’t connect it to the computer running v2rayN.
You don’t need to set up port forwarding on your router for local browser access. Don’t expose the local proxy listener directly to the public internet.

5. System proxy and TUN: start with one connection method

If the node is running but your browser isn’t using the proxy, the system proxy may not be configured. Open the v2rayN menu from the Windows system tray or macOS menu bar, then choose System Proxy → Automatically Configure System Proxy. “Automatically configure” here is a client menu command; it doesn’t mean the browser is using a PAC script.

System proxy

Recommended

Best for an initial test. The client adds the local proxy address to system settings, so browsers and apps that use the system proxy can connect. Apps that ignore this setting may still connect directly.

Use it to: verify web access and troubleshoot node or port issues.

In-app proxy

Enter the local HTTP or SOCKS address and port in a single app for targeted testing. If you already use a browser proxy extension, check whether it overrides system settings.

Use it to: proxy a specific app or check whether the system proxy is working.

TUN mode

Routes traffic through a virtual network interface, usually involving permissions, routing, and DNS. How it behaves depends on the operating system, core, and exclusion rules; it doesn’t guarantee that all traffic uses the proxy.

Use it when: the basic connection works but the target app doesn’t use the system proxy.

The system proxy determines how apps send traffic to the core; routing rules determine where that traffic goes next. Some destinations may still connect directly, even with the system proxy enabled. For your first test, keep the default routing rules and choose a destination that should use the proxy under those rules. Don’t test with a site that is already set to connect directly.

6. Test the connection: from core logs to a real request

A node’s latency reading only shows that a particular test got a response. It doesn’t confirm that web access, DNS, and the transport are all working. Follow the checks below in order, changing one thing at a time. Note the node, routing mode, and local port used for each test.

Check startup: After selecting an active node, make sure the logs show no configuration parsing failures, core exits, or listener port conflicts.
Check the proxy entry: Confirm that the browser uses the system proxy, or explicitly set an enabled local port in the app.
Check a request: Open an HTTPS page that should use the proxy under your current rules. Check whether it loads and look for related errors in the logs.
Check repeatability: Close and reopen the browser, then restart the client normally. Confirm the connection works again, not just once.

If curl is available on your computer, use it to test a specific local proxy port without relying on browser settings. The example below applies only if you’ve confirmed that 10808 is a SOCKS or mixed port. On Windows, use curl.exe; on macOS, you can use curl. The example domain is for testing the request; routing rules determine whether it uses the proxy.

curl.exe --proxy socks5h://127.0.0.1:10808 --connect-timeout 10 --max-time 20 -I https://example.com/

socks5h sends the destination hostname to the proxy for resolution. The 10-second value is the connection timeout; 20 seconds is the overall request timeout, not a measured latency. If the connection to the local port fails, check the core and listener first. If the local connection succeeds but the remote handshake fails, check the node settings, system time, and network connectivity.

7. Startup and common issues: enable auto-start after everything works

Once manual startup, subscription updates, and web access all work, go to Settings → Parameter Settings and look for the startup option in your version. On macOS, check System Settings → General → Login Items to see whether the app is allowed to launch at login. The labels may vary slightly between OS versions.

Use one startup method: Don’t add a system login item, shortcut, and client auto-start at the same time. Multiple instances can compete for the same port.
Startup isn’t connection: Launching the client at startup doesn’t guarantee that the core starts successfully or that the system proxy is configured.
Back up before updating: Exit normally and back up your configuration and subscription records first. Don’t overwrite files while the core is running.
Test after a restart: Check that the active node is still selected, the ports match, and the browser can still complete a real request.

No window appears after double-clicking. Do I need administrator privileges?

First check whether an instance is already running in the system tray or menu bar. Then check the package architecture and any runtime messages. Normal use of the Windows system proxy generally doesn’t require running as an administrator. Grant permission only when a feature such as a virtual network adapter requires it.

macOS says the app can’t be opened. Should I remove the restriction?

First verify the package source, chip architecture, and file integrity. If you’ve confirmed the app is trustworthy but macOS hasn’t approved it, check System Settings → Privacy & Security for an option to allow it to open. If macOS says the file is damaged or poses a risk, stop and get a trusted copy instead of disabling security protections across the system.

The subscription updated, so why can’t I access the internet?

Set one node as the active server, check the core logs, then confirm you chose System Proxy → Automatically Configure System Proxy. A successful subscription download only confirms that the configuration was retrieved; it doesn’t confirm that the node is reachable or the browser is using the local proxy.

What should I do if regular websites stop loading after I close v2rayN?

Reopen the client and choose Clear System Proxy. If the client won’t start, remove any leftover local proxy address from your system’s network proxy settings. Also check whether a browser extension is still forcing the old port, then test a direct connection again.

A successful first-time setup means your settings save, the core starts, one node completes a real request, and direct access works again after you quit. Once all four checks pass, add TUN, per-app proxy settings, or custom routing as needed. Troubleshooting is easier when you add them one at a time.