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

1. Choose the right package and a writable location

v2rayN is a graphical client for managing servers, subscriptions, and runtime settings; the core handles the actual connection. Downloading the client does not provide a working server. Before you start, make sure you have a server or subscription you are authorized to use, and that its protocol is supported by a core included in your package.

Windows and macOS packages are not interchangeable, and each system has separate x64 and ARM64 builds. On Windows, check your system type under Settings → System → About. On macOS, open the Apple menu → About This Mac to check your chip. Choose the ARM64 build for Apple silicon and the x64 build for an Intel processor. Package size alone is not a reliable guide.

• Windows archive: Extract the entire package to a location your user account can write to, such as C:\Users\YourUserName\Apps\v2rayN. Don’t launch the app from the archive preview, and don’t extract only the main executable.
• macOS app: Extract or mount the release package, then move the app to the Applications folder before launching it. Avoid running it long-term from a temporary mounted disk image.
• Dependencies and core: Keep the release package’s directory structure intact. A framework-dependent package may require a compatible runtime, while a self-contained package usually includes one. If you see a missing-component warning, follow the instructions for your package; don’t add arbitrary versions of shared libraries.
• Settings and backups: Quit the app and back up your existing settings before updating. The app directory and settings directory may be separate; their locations depend on the operating system and how the client was built.

2. First launch and subscription import

On first launch, check that the window opens, settings can be saved, and the core starts before enabling the system proxy. Otherwise, your system may send traffic to a local port with no service listening, making websites that normally work unreachable.

1. Check runtime requirements

   Launch the main app. If Windows reports a missing runtime, note the product name, architecture, and version in the message, then install the matching component. Don’t assume every missing-runtime warning refers to the same runtime.

2. Handle launch permissions

   If macOS blocks the app because its source can’t be verified, confirm where you downloaded it, then check System Settings → Privacy & Security for an option to allow it to open. If macOS reports that the file is damaged or security software flags it as risky, stop and verify the source. Don’t disable system protection outright.

3. Add a subscription group

   Go to Subscription Groups → Subscription Group Settings, enter a group name and the full subscription URL, then save. Some interfaces use a “+” button to add a group. Get the URL from your service provider; don’t use the address of its account dashboard.

4. Update subscription data

   Return to Subscription Groups and select Update All Subscriptions (Without Proxy). If your current network can’t reach the subscription source but you already have a working server, try Update All Subscriptions (Through Proxy). The latter can’t establish a connection by itself if you don’t have a working server yet.

5. Select an active server

   Select an entry in the server list, right-click it, and choose Set as Active Server. Check the logs for core startup errors. Then enable the system proxy and visit a known-working HTTPS site in your browser to confirm the connection—not just a latency result.

After importing a subscription, VMess, VLESS, transport, and TLS settings are usually generated for you; there’s no need to change them for “optimization.” If a server uses features such as REALITY, make sure the selected core supports that configuration. Seeing a server name in the client doesn’t guarantee the current core can run it.

3. Check the local listening port and system proxy

The local port is where apps connect to the client; the server port is where the client connects to a remote server. They are not interchangeable. The example below uses 127.0.0.1:10808 as a local mixed-protocol listener. It illustrates how to check your setup; it doesn’t mean every version should use the same port. Check the actual listener under Settings → Parameter Settings.

If your version has separate HTTP and SOCKS ports, don’t enter a SOCKS-only port in the system’s HTTP proxy field. After changing the listener port, restart the core or apply the settings as prompted, then update the system proxy so it doesn’t keep pointing to the old port.

• On Windows, enable the proxy from the tray menu or the main window under System Proxy → Set System Proxy. Before you finish, choose Clear System Proxy. The exact menu location depends on your interface.
• If macOS asks for permission to change network settings, make sure the request comes from the client you’re using. The app can open normally without the system proxy taking effect if it hasn’t been granted the required permission.
• For your first test, don’t run another proxy tool or a browser-specific proxy extension at the same time. Traffic could take a different route, making the client logs and browser results hard to reconcile.

4. Choosing between system proxy, TUN, and routing rules

The system proxy and TUN determine how traffic reaches the client; routing rules determine whether traffic goes direct or through a proxy once it gets there. They control different things. Set System Proxy doesn’t mean every connection uses a proxy, and the client doesn’t automatically know what each website needs.

Keep the built-in routing rules during initial setup; don’t rush to add a long list of custom domains. Rules are usually checked in order, so a broad rule near the top can override more specific ones below it. If a site only works through a direct connection or a proxy, check which rule matched and adjust that rule. Don’t change the core, DNS, and transport settings all at once.

5. Troubleshoot port conflicts and security software blocks

If the logs show address already in use or an error involving bind, first check whether another process is using the local listener. Common causes include two client instances running at once, an old core process that didn’t exit, or another app using the same port. The commands below check the example port 10808; replace it if your port is different.

Windows: Find the process listening on a port

netstat -ano | findstr ":10808"

Look for the port in a local address and a line with the status LISTENING. Seeing the same number in a remote address doesn’t mean your local port is occupied. The last column shows the process ID (PID); look it up under Task Manager → Details. Once you’ve identified the app, close it normally. Don’t end an unfamiliar system process.

macOS: Find the process listening on a port

lsof -nP -iTCP:10808 -sTCP:LISTEN

If the output points to an old client process, quit it from the menu and restart the app. If another program needs to keep using that port, change the local listener under v2rayN Settings → Parameter Settings, then update the system or app proxy to match. No output doesn’t mean your server works; it only means the command found no matching TCP listener.

• The main window opens, but the core won’t start: Check your security software’s quarantine history and the client logs to see whether a core file was removed. Don’t replace it with a same-named executable from an unknown source.
• A file was blocked: Note the file path, alert name, and time. After verifying the download source, decide whether to restore the file or add a targeted exception. Don’t add the entire downloads folder to a broad exception list.
• Can’t write settings: Check folder permissions, available disk space, and whether the file is read-only. You usually don’t need to run the app as an administrator for everyday system proxy use; fix the write permissions for the specific folder instead.

6. First-connection issues and checks before quitting

A complete first-time setup check covers four things: launch, import, access, and exit. When troubleshooting later, change one setting at a time and compare the logs before and after; that’s more likely to reveal the cause than repeated reinstalls. When asking for help, share your operating system, the client version, the selected core, and redacted error lines. Don’t include server passwords, full share links, or subscription credentials.

1. After restarting the app, the subscription group and active server are still set correctly.
2. With the system proxy enabled, the browser can reach the target site and the logs show no persistent core startup errors.
3. After turning off the proxy and quitting the client, sites that normally connect directly still work.