For Mac users installing v2rayN for the first time or setting it up again on a new device. Check the package architecture, Gatekeeper warning, local listener, system proxy, and network permissions in order. Identify the failing layer before reinstalling, changing proxy settings, or adjusting permissions.
Install v2rayN and handle the first-launch warning
Check your processor
Open the Apple menu → About This Mac. Choose the arm64 package for a Mac with Apple silicon, or the x64 package for an Intel Mac. Check the system requirements listed on the download page as well. A startup error caused by the wrong architecture cannot be fixed by changing network permissions.
Move it to Applications
Extract the archive or open the disk image, then drag the v2rayN app into the Applications folder in Finder. Once copying is complete, launch it from that folder—not from Downloads or from the disk image. Before upgrading, quit the old version and keep any configuration backups you need.
Check the exact warning
“Unable to Verify Developer” means macOS couldn't complete its trust check; it says nothing about whether a node works. Note the app name in the alert and confirm it matches the copy you moved to Applications. If the source is unknown or macOS says the app will damage your computer, don't open it—get a release from a known source instead.
Check for the app-specific option
In macOS 13 and later, open the Apple menu → System Settings → Privacy & Security, then scroll down to Security. After a blocked launch attempt, macOS may show an “Open Anyway” option for the app. Use it only if you've confirmed the release source, identified the correct app, and your device policy permits it. Authenticate as prompted, then confirm that you want to open the app. This exception applies only to that app; you don't need to change your Mac's overall security policy.
Starting with macOS 15, Control-clicking the app in Finder and choosing Open is no longer a reliable way to bypass this kind of signing or notarization block. If “Open Anyway” isn't shown, first confirm that the most recent block was for the installed copy you're trying to launch. Work-managed Macs may restrict this option; ask your administrator to check the policy instead of changing system-wide settings.
Tell Gatekeeper, proxy, and network permission issues apart
Use the symptoms to find the failing layer
RecommendedIf the main window doesn't appear, check the system alert first. If the window opens but the core exits, check the v2rayN logs. If the core is listening but your browser can't connect, check the proxy address and port. Change one thing at a time and note the original value before each change.
Best for: first-time installs, post-upgrade issues, and moving to a new Mac
Keep your existing system proxy
If your workplace network already uses a proxy or automatic proxy configuration, leave those settings as they are. In a test app that supports its own proxy settings, enter v2rayN's actual listening address. This lets you distinguish a core issue from a conflict with the system proxy.
Best for: when the existing proxy must stay in place or you only need to test one app
The system proxy is a setting that apps can use; it doesn't route all traffic. If an app uses its own proxy settings or connects directly, changing the system proxy may not affect its connection. v2rayN routing rules apply to requests that reach the core; changing the rules won't make an app that connects directly use the local listener.
Check the listening port and macOS system proxy
First check the local listener settings in v2rayN under Settings → Parameters, then verify them against the core startup log and actual listening ports. Field names, listener modes, and ports vary between versions. Don't copy an old tutorial that assigns separate ports to SOCKS and HTTP directly into System Settings. If your version uses a mixed inbound, check the actual configuration to see whether both protocols use the same port.
Check the local listener
- Server
- For local testing only:
127.0.0.1 - Port
- Check the current configuration and startup log
- Protocol
- Identify HTTP, SOCKS, or mixed inbound
- Status
- Make sure the core process is still running
A listening port only confirms that a process is using it; it doesn't prove the remote node is reachable.
Check the system proxy
- Where to find it
- System Settings → Network
- Service
- Your active Wi-Fi or Ethernet connection → Details → Proxies
- Proxy type
- Match the local inbound protocol
- Server and port
- Enter the local listener, not a remote subscription node
Before making changes, note any existing manual proxy settings, automatic proxy configuration, and exceptions so you can restore them.
After selecting “Set system proxy” in v2rayN, return to your active network service and check what was actually applied. If the app stops using the proxy after you switch to another network interface, check the settings for that service first. If the core log reports address already in use, use the example below in Terminal to find the process using the port. Replace the example port with the one shown in the error.
lsof -nP -iTCP:10808 -sTCP:LISTEN
Once you've identified the process using the port, decide whether to quit the old instance or assign a different port to the current one. If you change the port, update any system proxy or per-app proxy settings that still point to the old one. If web pages stop loading after you quit v2rayN, first check whether the system still points to a loopback port that is no longer listening. If you had a workplace proxy, restore the saved settings rather than clearing everything.
Common macOS network permission questions
Will denying Local Network access stop subscription updates?
Not necessarily. On macOS 15, Local Network permission covers access to devices on your local network; it's not a general internet access switch. If a public subscription update fails, check the logs to see whether the issue is a DNS failure, connection timeout, or server error. Only if the app needs to access local network resources, go to System Settings → Privacy & Security → Local Network and check its permission.
The firewall asks to allow incoming connections. Should I allow it?
If you're only using the system proxy on your Mac, don't open inbound access to your local network to fix outbound timeouts. Go to System Settings → Network → Firewall → Options to review the app's rule, and check whether the listener is bound only to the loopback address. The firewall's incoming connection rules and the core's ability to connect to a remote server are separate issues.
Why does my browser work while another app connects directly?
Check whether the app has its own proxy settings. If it supports manual configuration, choose the same protocol as the local listener, enter the loopback address and actual port, then retry the same request. If it only supports direct connections, a successful system proxy setup doesn't mean that app is using it.
The system asks to add a network configuration. Is that needed for a regular proxy?
First check whether you explicitly enabled TUN or another virtual networking feature. To test a regular system proxy, you can exit that mode and verify only the local listener and proxy settings for the current network service. If additional permission is requested, check what the prompt is asking to configure and why. On a managed device, ask your administrator whether it's allowed.