Follow this order: choose the right architecture → confirm the app’s source → handle the first launch → verify the system proxy → enable TUN if needed → configure login items. This guide is for users who already have a subscription but are stuck installing v2rayN or granting permissions on macOS. Get a standard proxy connection working first, then add TUN and launch-at-login settings so any issues are easier to isolate.
Check your processor architecture and app location
Open About This Mac from the Apple menu. If it shows an Apple chip, choose the ARM64 package; if it shows an Intel processor, choose the x64 package. The macOS and Windows builds of v2rayN are not interchangeable. Even if the interface launches, the bundled core may still have the wrong architecture. Check the selected release package’s notes for its minimum macOS version.
-
Check your architecture
Open the Apple menu → About This Mac and check Chip or Processor. You can also run
uname -min Terminal. On a native system, the command usually returnsarm64orx86_64, respectively. A terminal running under translation may affect the result, so check System Information first. -
Choose the right package
Go to the downloads page and select the v2rayN package for your macOS architecture. Keep the original download and extract all of its contents. If it’s a disk image, open it and copy the app to Applications.
-
Keep the app in a fixed location
Move the app to a permanent folder before launching it for the first time. Don’t run it from a mounted disk image long-term or drag out just one executable from inside the app bundle.
-
Launch the app once
Open v2rayN from Applications in Finder and note the exact wording of any alert. First determine whether it’s a developer verification warning, an alert that the app is damaged, or a core runtime error; then choose the appropriate next step.
This guide uses the menu names in System Settings; older macOS versions may show System Preferences. v2rayN’s settings may also be organized differently across versions. For ports and TUN options, use the fields shown in your installed version rather than copying paths from another platform’s desktop app.
Fix the “Apple cannot verify the developer” warning
Gatekeeper checks whether an app’s distribution is trusted. An “Apple cannot verify the developer” warning doesn’t mean your server connection failed, and changing your subscription won’t fix it. Allow the app to open only after confirming that the download came from a trusted source and matches the app you intend to run.
-
Read the warning carefully
If the app is blocked on first launch, close the alert. Make sure it refers to the v2rayN you just downloaded, not an older copy with the same name or an unfamiliar helper app.
-
Open Security settings
Open the Apple menu → System Settings → Privacy & Security, then scroll down to Security. A recent app block should appear here with details.
-
Allow this app only
If your system permits it and you’ve confirmed the app’s source, click Open Anyway next to the app. Authenticate as an administrator if prompted, then confirm that you want to open it. The button label may vary slightly by macOS version.
-
Launch it again
Open the same copy from Applications. If the option to allow it doesn’t appear, try opening the app again and check once more. On a managed device, also check whether your organization’s security policy blocks exceptions.
Don’t disable Gatekeeper for your entire Mac just to install one client, and don’t remove quarantine attributes from everything in Downloads. If allowing the app still doesn’t work, quit it, remove any questionable copies, and download a fresh release package for the correct architecture. That’s easier to troubleshoot than stacking unknown Terminal commands.
Verify the system proxy before enabling TUN
The v2rayN interface, proxy core, and system network settings are three separate layers. An open interface only confirms that the app runs. The core must successfully listen on a local port to provide a usable proxy endpoint. Only apps that follow the system proxy settings will use that endpoint when those settings are configured correctly.
Choose the connection method your apps need
Start with the system proxy
- Works for browsers and apps that follow the system proxy settings.
- First confirm that the server, core, and local listener are working.
- You don’t need TUN just to browse the web.
Use TUN if needed
- For traffic from apps that don’t follow the system proxy settings.
- Check the virtual interface, routes, and DNS.
- Grant any additional permissions first, then check which traffic is being routed.
The system proxy is an application-layer entry point; TUN captures traffic at the network layer. Neither can replace a valid server configuration and routing rules.
After importing your subscription and selecting a server, leave TUN off and choose Set system proxy automatically from v2rayN’s System Proxy menu. Don’t assume “automatic” means PAC; check which HTTP, HTTPS, or SOCKS proxy settings actually appear in macOS.
- Open System Settings → Network → your current Wi-Fi or Ethernet connection → Details → Proxies.
- Check the server address and port for each enabled proxy. For a local proxy, the address is usually
127.0.0.1, and the port must match v2rayN’s current listening port. - If the client asks to change your network settings, confirm which app made the request before authenticating. Canceling authorization, switching network services, or another proxy app overwriting the settings can prevent them from taking effect.
- Don’t disable the macOS firewall to fix outbound access. Controlling incoming connections and configuring an outbound proxy on your Mac are separate issues.
Use ports and commands to pinpoint permission issues
This example uses 10808 as the local HTTP proxy port; it isn’t guaranteed to be the default in every version. First check the local listening port and protocol in v2rayN under Settings → Parameters. If your version uses a different menu path, check its local inbound settings instead.
scutil --proxy
lsof -nP -iTCP:10808 -sTCP:LISTEN
curl -I --connect-timeout 15 --max-time 30 --proxy http://127.0.0.1:10808 https://example.com/Use scutil --proxy to inspect the current proxy configuration and lsof to check for a local TCP listener. If there’s no listener, check the core logs for a startup failure, incompatible architecture, or address conflict. Don’t keep retrying system proxy permissions. A listener alone doesn’t confirm that the port accepts HTTP; verify the inbound protocol too.
Explicit proxy request succeeds
- What the command returns
- Received HTTP response headers from the destination
- Browser behaves unexpectedly
- Check the system proxy and browser settings first
- Check the system configuration
- Verify the address and port in scutil --proxy
A response only confirms that this request reached its destination; it doesn’t mean every domain or route is working.
Explicit proxy request fails
- Connection refused
- Check the port, listener, and inbound protocol
- Handshake timed out
- Check the server address, network, and outbound logs
- Certificate error
- Check the system clock, server hostname, and TLS settings
A curl command with an explicitly specified proxy doesn’t depend on the system proxy setting, making it useful for isolating application-layer configuration issues.
If the local port provides SOCKS only, test with --proxy socks5h://127.0.0.1:10808 and substitute the actual SOCKS port. Here, socks5h means the proxy resolves the destination hostname; that’s different from resolving it on your Mac.
Grant TUN and network permissions only when needed
Once a standard proxy test succeeds, try the client’s Enable TUN option. Creating a virtual network interface, changing routes, or enabling a related helper service may require administrator privileges. The exact behavior depends on your v2rayN version and TUN component, so don’t expect the same system prompt every time.
- Check the startup logs first: Note the first error that appears when you enable TUN. Handle insufficient permissions, interface creation failures, and DNS timeouts separately.
- Verify authentication requests: If macOS asks for administrator authentication, check when the request appeared and which app initiated it. Never enter your subscription password or server credentials in a system authorization prompt.
- Follow the prompt to the right settings: Check locations such as System Settings → Network → VPN & Filters only if you actually see a VPN configuration or network extension request. On some newer versions, extensions are managed under General → Login Items & Extensions.
- Local Network access is separate: On macOS 15 and later, Privacy & Security → Local Network controls access to devices on your local network. It isn’t a master switch for all internet access. If the app isn’t listed, that alone doesn’t mean TUN permissions failed.
- Rule out conflicts: Temporarily disable other tools that change the default route, DNS, or system proxy, then test v2rayN on its own. Don’t run multiple TUN traffic-capture tools at the same time.
Configure login items and verify recovery after quitting
Launching at login, running in the background, and TUN authorization are separate settings. Adding v2rayN to Login Items only attempts to launch the app when you sign in. It doesn’t guarantee that a server will be selected, the system proxy configured, or TUN started. Those actions also depend on the client’s startup options and macOS permissions.
-
Add a login item
Open System Settings → General → Login Items; some versions show Login Items & Extensions. Under Open at Login, add v2rayN from Applications.
-
Prevent duplicate launches
If you’re already using v2rayN’s launch-at-startup option, first check whether it’s already listed in System Settings. Keep just one clear launch method to avoid having both an old and a new app path.
-
Check background items
Check the names and sources in the Allow in the Background list only if your current version actually installs related helper items. If no such item appears, that doesn’t mean the app is installed incorrectly.
-
Test what happens when you quit
Quit the app from its menu rather than just closing the window. Check whether the system proxy settings are restored. If web access stops working, go to Network → your current network service → Details → Proxies and remove any leftover local proxy settings.
Finally, log out and back in to confirm that the app launches from its permanent location, the core can listen, and the system proxy or TUN works as expected. If it stops working after waking from sleep, recheck the listener, proxy settings, and DNS in that order. Restarting your Mac shouldn’t be your only troubleshooting step.
Common warnings and what to do
The “Open Anyway” button isn’t there. What should I do?
Try opening the app again from Applications, then check the relevant block under Privacy & Security. If this is a work-managed Mac, check whether your organization’s policy prevents exceptions. If the warning mentions malware, don’t continue as if it were a routine developer verification prompt.
The app opens, but why do core errors keep appearing?
First check the package architecture and make sure the download is complete. Then look at the core name, executable path, and first error in the logs. Allowing the main app doesn’t necessarily allow a separate core executable. If macOS blocks a child process, confirm that it belongs to the same release package before allowing it; don’t approve unfamiliar programs blindly.
The browser works, but Terminal commands fail to connect. Why?
Many command-line tools don’t automatically use the macOS system proxy. First test with the explicit-proxy curl command in this guide, then configure proxy environment variables according to the tool’s documentation. Don’t keep requesting system network permissions just because a Terminal request failed.
After an update, macOS asks to verify the app again. Will the old login item still work?
A new version may trigger another security check. Confirm its source and follow the steps for allowing a single app. If the app’s folder or name changed, remove the old path from Login Items and add the new one. Then check the port and startup options, and don’t run two copies at once.
For troubleshooting, record only the macOS and v2rayN versions, processor architecture, time of the error, and a redacted error line. Remove subscription URLs, server credentials, and identifiable network information before sharing logs. For help with importing subscriptions or routing concepts, see the getting started and advanced guides on this site.