Installing v2rayN on a Mac for the first time? Choose the package for your processor, then follow the macOS prompts to approve the app if needed. Once it opens, test the system proxy first and TUN separately. This helps pinpoint whether the issue is app launch, the proxy core, or macOS network settings.
Apple Silicon or Intel: Choose the Right Installer
Open the Apple menu “” and select “About This Mac.” If it lists “Chip” followed by an Apple M-series name, choose ARM64. If it lists “Processor” followed by an Intel name, choose x64. For either architecture, check the minimum macOS version listed for the current release. A matching processor architecture does not guarantee your macOS version is supported.
Native ARM64 Package
RecommendedFor Apple silicon Macs, use the macOS package labeled ARM64 or arm64. If you unexpectedly see a prompt to install Rosetta on first launch, check the architecture of both the download and the core you’re using.
For: Apple silicon Macs
Native x64 Package
For Intel Macs, choose the x64 or x86_64 package. An ARM64 package won’t run on an Intel Mac, and changing privacy settings won’t fix an architecture mismatch.
For: Intel Macs
For a disk image download, open the image and drag v2rayN to Applications. Eject the image, then launch the app from Applications. For an archive, extract it completely and move the app as instructed for that release. Don’t launch it from the archive preview or move core files out of the package on their own.
Gatekeeper: Where to Click “Open Anyway”
“Apple cannot check it for malicious software” is a system check at launch; it has nothing to do with subscriptions, nodes, or network permissions. Only create an exception for this app if you trust its source, have confirmed it’s the expected release, and your device management policy allows it. If macOS warns that the app will damage your computer or has detected malware, stop and verify the source. Don’t treat that as a routine developer verification warning.
Launch from Applications
Open Applications in Finder and double-click v2rayN. Note the app name and exact warning, then dismiss it. Verify the name before allowing it, so you don’t accidentally approve another app blocked around the same time.
Open Security Settings
On macOS 13 and later, open “” → “System Settings” → “Privacy & Security,” then scroll down to Security. Check there right after the app is blocked. This option applies to a recent launch attempt and may not remain visible.
Allow This App
Make sure the Security section names v2rayN, then click “Open Anyway.” Authenticate if prompted, then choose Open in the confirmation dialog. If the option isn’t available on a managed device, contact your administrator instead of changing system-wide security settings.
Check That It Launched
Wait for the main window to appear before configuring subscriptions or the proxy. If the window opens but the logs show that the core failed to start, the app launch itself is working. Check the core architecture, whether all files are present, and whether its listening port is already in use.
System Proxy: Check the Local Listener, Then the Network Service
Turn TUN off first and select a node you know works. In v2rayN, open Settings → Parameter Settings to check the local listener, then select “Set system proxy automatically” under System Proxy on the main screen. Button locations may vary by version. The example numbers below are for checking addresses and ports, not universal defaults.
- Check the active connection. In System Settings → Network, select the connection you’re using. For Wi-Fi, open Wi-Fi → Details next to the connected network → Proxies. For a wired connection, check the relevant Ethernet service. Proxy settings on an old service don’t confirm that they’re configured on a newly selected one.
- Use the matching proxy type. Check the address and port configured for the enabled web proxy or SOCKS proxy, and match them to the listener protocol. Don’t enter a SOCKS-only port for an HTTP proxy. If your version uses a mixed listener, check which protocols that listener actually supports.
- Test a browser request. In a browser that follows system proxy settings, open a webpage you know is reachable and check whether v2rayN logs a new request. If a request arrives but the connection fails, check the node and routing first. If no request appears, check whether the browser has its own proxy settings and whether the proxy is active on the current network service.
Before enabling the system proxy, note any existing manual proxy settings or automatic configuration URL. When testing is done, clear the system proxy set by v2rayN before quitting, then confirm the original settings are restored. Otherwise, your browser may keep trying to connect to a local port that is no longer listening.
TUN and Network Extensions: Grant Only the Permissions You Need
The system proxy works with apps that follow proxy settings. TUN routes traffic through a virtual interface, making it useful for testing apps that ignore system proxy settings. TUN and network extensions aren’t the same thing: depending on the version, TUN may require administrator approval, a privileged helper, or a system VPN configuration or network extension prompt. If no extension prompt appears, that doesn’t mean you missed a setup step.
- First confirm that the node works in system proxy mode. To test TUN, clear the system proxy settings written during this session, keep any necessary network management configuration, and enable TUN on its own. This makes it easier to tell which route is carrying traffic.
- If macOS asks to add a VPN configuration or allow a network extension, check the app name in the prompt and make sure it matches the action you just took. On macOS 15, check System Settings → General → Login Items & Extensions → Network Extensions for the relevant entry. Enable it only if this version actually uses that extension and the entry matches the prompt. If administrator approval is required, have an authorized account approve it in the system dialog.
- After enabling TUN, test webpages and local network resources, then check the logs for interface creation, DNS, or routing errors. If work resources become unreachable, turn TUN off and confirm the original connection is restored before checking for conflicts with an existing VPN, subnet routes, or company policies. Change one thing at a time so you can tell a routing fix from a node change.
First Launch and Connection Troubleshooting
Why Can’t I See “Open Anyway”?
Try launching v2rayN again from Applications, dismiss the blocked-app warning, then immediately return to the bottom of Privacy & Security. If the warning indicates an incompatible architecture or an unsupported macOS version, choose a compatible package. If device management policy blocks the app, ask your administrator.
The Subscription Updated Successfully. Why Won’t Any Webpages Load?
A successful subscription update only means the subscription URL was reachable and its configuration was retrieved. It doesn’t confirm that the selected node works. Select the node you want to use, check the core’s listening status in the logs, then compare the port with the Proxies page for the active network service. If requests appear in the logs but the handshake fails, check the node configuration; you don’t need to authorize the app again.
Why Does My Browser Lose Its Connection After I Quit v2rayN?
Check whether the active network service is still sending web requests to a loopback address. If the remaining proxy was set during this test, reopen v2rayN, clear the system proxy, then quit—or restore the values you noted earlier in Network settings. If you used TUN, also make sure it’s turned off.