This guide is for anyone installing v2rayN on a Mac for the first time or troubleshooting an app that won't open or a system proxy that isn't working. Choose the build for your processor, move the app to Applications, then use macOS's per-app exception to launch it. Next, check the local listener, system proxy, and any network permissions the app requests. Allowing an app through Gatekeeper doesn't mean the proxy connection works, and an administrator prompt doesn't mean you need to disable macOS security features.
Choose the right installer: check your chip and macOS requirements
Open the Apple menu in the top-left corner and choose “About This Mac.” If it says “Chip Apple M…,” choose Apple Silicon (ARM64). If it says “Processor Intel…,” choose Intel (x64). Don't guess based on the Mac's appearance or purchase date: the same product name can refer to models with different processors.
Native Apple Silicon build
RecommendedFor Macs with Apple silicon; downloads are typically labeled arm64. “Recommended” means Apple silicon Macs should use the build for their native architecture—not that every Mac should choose this package.
For: Macs that show an Apple chip in About This Mac.
Native Intel build
For Intel Macs; downloads are typically labeled x64. Intel Macs can't run ARM64 builds. Some Intel apps on Apple silicon may require Rosetta, but emulation shouldn't be the default for a first-time install.
For: Macs that show an Intel processor in About This Mac.
Go to the client download page, select the macOS option, and check the minimum macOS version listed for that release. Choose the macOS desktop app, not the Windows WPF package. If macOS says Rosetta is required on an Apple silicon Mac, go back and check that you downloaded the right architecture. The app and its bundled core should also match; don't mix in executables for a different architecture from an old folder.
- Fully extract archives before moving the app to Applications. For a disk image, open it first, then drag the app into Applications.
- Quit any older version before replacing the app. On first launch, don't run a temporary copy from the archive preview or disk image.
- Before updating, use the client's backup or export feature to save your settings. Don't upload backups containing subscription URLs to a public location.
Gatekeeper block: allow this app with “Open Anyway”
“Cannot verify the developer” and “Apple cannot check it for malicious software” are app trust warnings, not problems with your nodes, DNS, or subscription. First confirm the file came from the expected release source, then use macOS's exception for that specific app. These steps apply to macOS versions with System Settings; wording may vary slightly between versions.
-
Open the app once
In Finder, go to Applications and double-click v2rayN. If macOS blocks it, read the warning, close the dialog, and leave the launch attempt recorded.
-
Open Security settings
Go to Apple menu → System Settings → Privacy & Security. Scroll to the Security section and check that the blocked app listed is the v2rayN you just tried to open.
-
Allow this app
Click “Open Anyway” next to the app entry. If prompted, authenticate with Touch ID or an administrator account, then click “Open” in the confirmation dialog.
-
Check the main window
Once the app launches, check its main window and logs for core startup errors. An open window only confirms the app is allowed to run; you still need to check the proxy listener and network settings.
Some older macOS versions let you trigger an exception by Control-clicking the app in Finder and choosing “Open,” but newer versions may not offer this option. Prefer the setting under Privacy & Security. You don't need to disable Gatekeeper for the whole Mac or turn off System Integrity Protection.
First connection: distinguish the local port from the system proxy
In v2rayN, import your own subscription, update it, and select a working node as the active server. Check the local listening port under Settings → Parameters Settings, then choose “Set system proxy” from the main window or the menu bar icon's System Proxy menu. The menu location may vary between desktop releases; use the equivalent option shown in your version.
This example uses 127.0.0.1:10808 for a local listener that supports HTTP proxying. It isn't a guaranteed default port for every release. If your client shows a different port, or uses separate HTTP and SOCKS listeners, point the system's web proxy to the actual HTTP endpoint instead of copying this example.
After enabling the proxy, open System Settings → Network → your current Wi-Fi or Ethernet service → Details → Proxies. If you're configuring a manual HTTP system proxy, check that Web Proxy (HTTP) and Secure Web Proxy (HTTPS) point to the correct local address and port. The HTTPS proxy setting tunnels HTTPS requests through the HTTP proxy; it does not mean the local endpoint must use TLS.
Example client listener
- Listen address
- 127.0.0.1
- Listen port
- 10808
- Supported proxy type
- HTTP proxy
- Active server
- Selected working node
First confirm the logs show the core started successfully. Replace the example values with your actual settings.
Example system proxy settings
- Web proxy
- 127.0.0.1:10808
- Secure web proxy
- 127.0.0.1:10808
- Proxy authentication
- Fill in only the settings for the local endpoint
- Network service
- The network service currently in use
If the client is using PAC, check the automatic proxy configuration URL. Don't add a manual proxy from an untrusted source on top of it.
The system proxy affects only apps that honor this setting. If a browser works but a command-line tool still connects directly, that doesn't automatically mean authorization failed; the tool may need its own proxy arguments. Conversely, seeing the proxy enabled in System Settings doesn't prove the core is listening. Check each separately.
Network permissions: distinguish administrator access, local network, and TUN
macOS doesn't have a single “allow all proxy traffic” switch that needs to be enabled. When a permission prompt appears, check which app is requesting access and what it wants to change. The system proxy, local network access, and virtual network interface serve different purposes; don't enable every permission just because a webpage won't load.
| Prompt or setting | What it does | What to do |
|---|---|---|
| Administrator authentication | Change protected network settings or install a required helper component | Check which process is requesting access and what it will do. Approve only if it matches the client action you just performed. Never enter your password in a subscription or node form. |
| Privacy & Security → Local Network | Control an app's access to local network resources, such as devices on your LAN | This permission may appear on macOS 15 and later. Allow it only when a local network feature needs it; it is not a general switch for internet access. |
| TUN privilege prompt | Create a virtual network interface or change routes or DNS settings | Enable this only if your release supports it and you need to route traffic from apps that don't follow the system proxy. Follow the client's instructions to grant access. |
| Network → Firewall | Manage incoming connections | Turning off the firewall usually won't fix a local proxy's outbound connection. Check the relevant inbound rule only if another device needs to connect to your Mac. |
If v2rayN isn't listed under Local Network, that doesn't mean the installation is incomplete. Apps usually appear in this list only after they request the relevant access. Using a local proxy over a loopback address alone doesn't mean you need to grant this permission. On a managed work Mac, organizational policies may control network extensions or proxy settings; ask your administrator rather than removing management profiles yourself.
Troubleshoot connections: check the listener, then the active network service
If the system proxy is on but webpages still won't load, troubleshoot in this order: local endpoint, system settings, then remote connection. Quit other tools that modify the system proxy to prevent them from overwriting each other's settings. The commands below only read status; run them in Terminal under Applications → Utilities.
# Check whether the example port has a TCP listener
lsof -nP -iTCP:10808 -sTCP:LISTEN
# List network services and confirm the name of the service in use
networksetup -listallnetworkservices
# Example using the service name Wi-Fi
networksetup -getwebproxy "Wi-Fi"
networksetup -getsecurewebproxy "Wi-Fi"
networksetup -getautoproxyurl "Wi-Fi"- No listener shown: Check the v2rayN logs for a core exit or a different port. If the port is already in use, identify the process using it or change the port in the client, then configure the system proxy again.
- System proxy points to an old port: Clear the system proxy in the client, then set it up again. If configuring it manually, update both web proxy entries for the network service you're currently using.
- Service name lookup failed: Replace
Wi-Fiin the command with the exact network service name from the list. Keep the English double quotes if the name contains spaces. - Listener and system settings look right: Check the logs for remote connection, TLS, or domain resolution errors. A timeout may mean the server is unreachable. For certificate errors, check the system clock and the node's TLS settings; don't skip certificate verification as a workaround.
You can also test the local HTTP proxy directly with the request below. It specifies the proxy explicitly and doesn't rely on the system proxy setting; replace the example port with the one in use. The target is this site's homepage. Results depend on your network, node, and the target site's status, so one request can't establish whether every app is working.
curl --proxy http://127.0.0.1:10808 --head --max-time 15 https://v2raydns.com/If the request can't connect to 127.0.0.1, check the local listener first. If it connects locally but the remote request fails, check the active node and logs. If the explicit proxy request works but your browser doesn't, check for a separate browser proxy, an old PAC setting, or an extension overriding the proxy. Don't keep changing DNS before the local endpoint works.
FAQ: What to check after allowing the app to open
Why is there no “Open Anyway” button?
Try launching the app again from Applications, then immediately check the Security section near the bottom of System Settings → Privacy & Security. Confirm the warning is about developer verification, not malware or an organizational policy. If the option still doesn't appear, note your macOS version and the full warning. Don't disable security checks for the entire Mac.
The app is allowed to open. Why do the logs still say permission denied?
Gatekeeper only controls whether the app is trusted to run. Check whether the error relates to running the core, writing to the configuration directory, or TUN privileges. Make sure the app was fully moved to Applications and your account can write to the configuration directory the client actually uses. Don't run the entire desktop app as an administrator to mask a directory permission problem.
Do I need to grant permission again after switching Wi-Fi networks?
First check Network → Details → Proxies for the active network service. Switching from Wi-Fi to Ethernet may switch to a different service with different proxy settings. In v2rayN, set the system proxy again, then check the address and port. Don't mistake differences between network services for another Gatekeeper block.
What if the entire browser loses internet access after I quit the client?
Start v2rayN, choose “Clear system proxy” from the System Proxy menu, then quit. If the app won't launch, open the Proxies settings for the active network service and turn off any web proxy pointing to the old local port, or disable the old PAC configuration. Remove only settings belonging to this client; check with your administrator before changing a proxy required by your organization.
Finish setup: keep a way to restore your network settings
After setup, run through the full sequence at least once: start the client → enable the system proxy → confirm you can browse → clear the system proxy → quit the client. This verifies that the connection relies on an active listener and correct settings, not browser cache or another leftover proxy. When updating the app, changing nodes, or enabling TUN, change one category of settings at a time to make issues easier to trace.
- Keep a note of the actual local listening port and the name of the active network service for future reference. Don't include subscription URLs in public troubleshooting screenshots.
- Before sharing logs, redact server addresses, user identifiers, subscription tokens, and other sensitive details. Include only the error type and necessary context.
- Before uninstalling, turn off TUN if enabled and clear the system proxy. Deleting the app doesn't necessarily restore network settings.
- To learn how to import subscriptions and configure DNS, follow the getting started guide one step at a time. Avoid changing the core, routing, and DNS policies all at once.