v2rayN First-Time Setup Checklist for Windows and macOS

Choose the right build: OS, architecture, and edition

v2rayN is a desktop client for managing servers, starting proxy cores, and configuring the system proxy. Installing it does not provide a working server connection. Before downloading, check your operating system and processor architecture—not just the file size. Windows x64 and ARM64 builds, and macOS Intel and Apple silicon builds, are different. A client that opens successfully may still include a core that is incompatible with your system.

• Windows: Open Settings → System → About and check the processor architecture under “System type.” Most Intel and AMD desktop PCs use x64; for ARM devices, follow the download page’s build guidance.
• macOS: Open the Apple menu → About This Mac and check “Chip” or “Processor.” Choose the matching ARM64 build for Apple silicon or the x64 build for an Intel Mac.
• Edition: The cross-platform desktop edition supports Windows, macOS, and Linux. The classic WPF edition is for Windows. Their menus differ, so don’t expect buttons to appear in exactly the same place in both versions.

Install location: extract everything before launching

Don’t run an archive directly from the preview window in your compression utility. The main program may depend on nearby core files, resources, or configuration files. Extracting only the executable can leave the interface working while the core fails to load. Installers, archives, and disk images each work differently, so follow the instructions for your package.

1. Check the package type

   Run an installer and follow its prompts; extract archives completely to a permanent folder first. On macOS, if the download is a disk image, open it and move the app to Applications rather than running it from the mounted image.

2. Choose a permanent location

   For a Windows portable build, use a writable folder such as D:\Apps\v2rayN. Avoid temporary folders, archive preview locations, and synced folders. A folder name containing non-Latin characters is not automatically a problem; make sure the folder is writable and all files are present.

3. Handle startup warnings

   If Windows reports a missing runtime, note its name and architecture, then install what the package requires. Don’t download DLLs at random. If macOS can’t verify the developer, confirm the app’s source, then check System Settings → Privacy & Security for an option to allow it.

4. Start normally the first time

   Run the app as a standard user and test only system proxy mode at first. Leave TUN off, and don’t elevate permissions just to see if that fixes things. This helps separate permission issues from server issues.

5. Keep a record of the setup

   Open Help → About and note the client version. Check the logs for the core name and version. Quit and reopen the app once to confirm your servers are still there and the configuration was saved.

Core startup: check the interface and proxy separately

The v2rayN interface is not the core process that forwards traffic. After selecting a server and setting it as active, confirm that the core starts successfully and listens on a local port. Log messages such as “file not found,” “permission denied,” and “address already in use” point to different causes. Repeatedly clicking Connect won’t fix them.

Go to Settings → Parameter Settings and look for the core selection or “Core type” option in your version. Confirm which core the server uses; if the layout differs, rely on the feature name and runtime logs. Don’t switch every configuration to a particular core just because a server is labeled V2Ray. VMess and VLESS are protocols; Xray is a core implementation. The server may also require specific transport and security settings.

• Core files are missing: Check that you downloaded a complete package containing the required core. If the build requires you to add a core separately, put it in the specified location as instructed. Don’t rename files arbitrarily.
• VLESS and REALITY: Make sure the selected core supports the combination required by the server. Keep the server name, public key, short ID, and flow exactly as provided by the subscription; don’t guess these values.
• VMess and system time: If the logs show an authentication or time-related error, check automatic clock synchronization first, then verify the server settings. A significantly incorrect system clock can also interfere with TLS certificate validation.
• Quit older processes: Exit any other copy of v2rayN from the system tray or menu bar before launching the current version. Two client instances may start separate cores and compete for the same listening port.

Import a subscription: verify the source, then test one server

The client package does not include server connection details. Your service provider supplies the subscription URL, which usually contains access credentials and should be protected like a password. Don’t share the full URL in screenshots, public forums, or online parsing tools. When asking for help, share the status code and error message, but redact any tokens in the URL.

1. Open Subscription Group → Subscription Group Settings, add a group, and enter a recognizable name and subscription URL. Depending on the edition, the add action may appear as “Add” or a “+” button.
2. After saving, open the Subscription Group menu and update the group. If you don’t have a working proxy yet, try updating without one first. Only try updating through a proxy if a direct update fails and you already have a working server.
3. After a successful update, check that servers were actually added to the list. A group name with no servers may mean the response was empty, the subscription expired, or the current version doesn’t support its format. Check the update logs first.
4. Select a server, then choose Set as active server from the context menu. Check the core logs afterward. Selecting a row in the server list alone doesn’t switch the active outbound server.

For your first test, select just one server; there’s no need to repeatedly benchmark the entire subscription. A successful latency test only means that the test request received a response. It doesn’t prove that your browser is using the proxy or that download speeds meet a particular target. First load a real webpage through that same server, then compare other servers. This makes results easier to reproduce.

System proxy and ports: establish a browser baseline first

System proxy and routing are separate settings. The system proxy determines whether an app sends requests to the local proxy; routing determines how requests that reach the core are sent onward. For an initial test, choose Set system proxy automatically from the System Proxy menu in the v2rayN window or tray, and leave the default routing settings in place. Enabling the system proxy doesn’t capture traffic from every program; some apps ignore it.

On Windows, check the system proxy under Settings → Network & Internet → Proxy. On macOS, go to System Settings → Network → your current connection → Details → Proxies. The exact names may vary by OS version. Let the client configure the proxy first, then verify the result in system settings to avoid conflicting changes.

curl -I -x http://127.0.0.1:10808 https://example.com

The command above applies only if your configuration provides an HTTP or mixed proxy on 10808. On Windows, use curl.exe to avoid issues with command aliases. It explicitly sets a proxy, helping distinguish a working local proxy from a system proxy that the app hasn’t picked up. An HTTP response means that request received a response; it’s not a speed test. If the connection is refused, check the listening port first. For TLS or remote connection errors, consult the core logs.

• Command works, browser doesn’t: temporarily disable browser extensions that set their own proxy, and check whether they use a different port.
• Neither the command nor browser works: first confirm the core is running, then check the active server and logs. Don’t immediately change DNS, Mux, and every routing rule.
• Only some sites fail: note the domain, time, and routing rule that matched, then investigate DNS or routing. Don’t assume a single failed webpage means the installation package is at fault.

Startup and shutdown: make sure the proxy doesn’t linger

Set up launch at startup only after you’ve verified the connection. Launching the client automatically, minimizing it on startup, and automatically setting the system proxy are separate options. An app running in the background doesn’t mean the system proxy is configured; an enabled system proxy doesn’t guarantee the last active server still works. After setup, test both a quit and relaunch, and a fresh sign-in.

• In the client: Go to Settings → Parameter Settings and look for options to launch at startup or minimize on launch. Enable them as needed. If your build has no such options, use your operating system’s startup settings.
• On Windows: Check startup apps under Settings → Apps → Startup. Avoid configuring the app to launch through a shortcut, Task Scheduler, and the client’s own startup option all at once.
• On macOS: Check whether the app is allowed to launch at login under System Settings → General → Login Items. If you move the app, verify that the login item still works.
• Before quitting: Choose Clear system proxy from the System Proxy menu, then exit the client. Open a regular webpage to confirm that your direct connection works again. If your organization’s network proxy was configured before, restore its settings rather than clearing them outright.

Common first-install issues: change one thing at a time

You can verify a successful setup with specific checks: the client still loads its configuration after a restart, the active server starts its core, your browser can access the web through the system proxy, direct access returns after quitting, and launch-at-login behaves as expected. Keep the client and core versions, listening port, and a log from one failed attempt; these details are more useful for troubleshooting than “it won’t connect.” Remember that backups may contain subscription credentials and server keys—don’t upload them publicly.