This guide is for users who have downloaded the v2rayN desktop app but are blocked by a macOS security warning on first launch, or whose system proxy cannot be applied after launch. First confirm the app source and build, then approve it in Privacy & Security. Remove the quarantine attribute only if standard approval fails, and finally verify the core, listening port, system proxy, and firewall.
Identify Where macOS Is Blocking the App
When macOS first opens an app downloaded from a browser and extracted from an archive, it checks the app signature, source marker, and quarantine attribute. The “cannot verify the developer” warning usually appears before the program code actually runs, so changing subscriptions, nodes, routing, or DNS will not help. Grant the explicit system approval first, then continue configuring v2rayN.
If the v2rayN main window appears and macOS later asks whether to allow incoming network connections, the app has passed its launch checks and the issue is firewall permission. This permission mainly affects local listening ports and LAN sharing. Denying incoming connections usually does not prevent v2rayN from creating outbound connections to remote servers, but it may stop other apps from reaching the local proxy port it exposes.
A third case is when the window and core start normally and node tests return results, but the browser still connects directly or cannot reach the network. This is usually caused by the system proxy not being applied, a mismatch between the proxy port and the active listening port, or an old process still holding the port. Handle these separately instead of repeatedly deleting the app or re-importing the subscription.
Approve the App in Privacy & Security
RecommendedSystem Settings records approval for this launch, and the change applies only to the v2rayN app that was just blocked.
Best for: the first “cannot verify the developer” or “app was blocked” warning
Open with Control-Click
Open the app again from Finder’s context menu. On some macOS versions, a confirmation dialog with an “Open” button appears.
Best for: double-clicking shows only a Close button, while the app name and source have been verified
Remove the Quarantine Attribute
Use Terminal to clear the download quarantine flag from the specified app bundle without changing subscription, routing, or core settings.
Best for: repeated blocks after standard approval, once the app path has been confirmed
Approve v2rayN on First Launch
Move the extracted v2rayN.app to the Applications folder before opening it for the first time. Running it directly from Downloads or an archive preview can cause path changes, unwritable components, or another security check on the next launch. After moving it, double-click the app once so macOS creates the corresponding block record.
-
Create the Block Record
In Applications, double-click v2rayN. When “cannot verify the developer” or another block message appears, click “OK” or “Cancel” instead of deleting the app immediately.
-
Open the Security Panel
Open Apple menu → “System Settings” → “Privacy & Security”, scroll down to the Security section, and find the recent record for blocked v2rayN.
-
Open Anyway
Click “Open Anyway” and complete local account authentication if requested. When a second confirmation dialog appears, click “Open”.
-
Allow Network Access
If macOS asks whether to allow incoming network connections, allowing them is reasonable for local-only use; you can change this later in “System Settings” → “Network” → “Firewall” → “Options”.
-
Check the Core
Open v2rayN “Settings” → “Parameters” → “Core Type”, confirm that the selected core supports the current node protocol, then save and restart the core.
macOS 12 uses slightly different names: the corresponding path is usually “System Preferences” → “Security & Privacy” → “General”. If “Open Anyway” is missing, return to Finder and double-click v2rayN again, then immediately open Security settings after the new block record is created. The button appears only for the app most recently blocked by macOS.
You can also Control-click v2rayN.app in Finder, choose “Open”, and select “Open” in the confirmation dialog. This differs from double-clicking, but the available buttons vary by macOS version. If Control-clicking still shows only a Close option, use the Security panel instead of repeatedly relaunching the app.
Handle Network Prompts and a System Proxy That Is Not Working
After launch, v2rayN listens on a local loopback address and browsers or the system proxy send requests to that port. Troubleshooting must distinguish between whether the core is listening and whether the system is using that listening port: the first confirms that a local proxy service exists, while the second confirms that app traffic actually passes through it.
Use the port currently shown in v2rayN. 10808 is a common example, not a fixed value for every version or migrated configuration. If Parameters shows 10809, 10810, or another port, use that same number for the system proxy and Terminal test commands.
- Check the runtime log first: After starting the core, look for port conflicts, configuration parsing failures, non-executable core files, or node connection errors. Fix the core layer before switching the system proxy repeatedly.
- Then check the system proxy: Open “System Settings” → “Network” → the active network interface → “Details” → “Proxies”. Check whether Web Proxy, Secure Web Proxy, or SOCKS Proxy points to 127.0.0.1 and uses the same port as v2rayN.
- Check proxy mode: If v2rayN is set to clear the system proxy, the browser will not automatically use the local port. Switch to setting the system proxy, then reopen the browser for testing.
- Check LAN listening: For local-only use, prefer 127.0.0.1. Enable connections from the local network only when other devices on the same LAN genuinely need access, and review the firewall rules at the same time.
- Rule out an old process: After an abnormal exit, the old core may still hold the port. Quit v2rayN, end the corresponding core process in Activity Monitor, and then start the app again.
Remove the Quarantine Attribute When Approval Fails
If you have already selected “Open Anyway” in Security settings but the block warning returns on every launch, check whether the app bundle still has a download quarantine attribute. The command below applies only when the app is in Applications and is definitely named v2rayN.app. Confirm the actual path in Finder before entering it.
xattr -p com.apple.quarantine "/Applications/v2rayN.app"If the command returns one line of quarantine information, the attribute is present. If it reports that the attribute does not exist, no removal is needed; check the app bundle permissions, core startup log, or whether the downloaded files are complete instead. Once the path is confirmed, recursively remove the quarantine attribute from this app bundle:
xattr -dr com.apple.quarantine "/Applications/v2rayN.app"Run the check again afterward. Normally, it will return no quarantine information:
xattr -p com.apple.quarantine "/Applications/v2rayN.app"If the app is in another folder, do not copy “/Applications/v2rayN.app” as-is. Drag v2rayN.app from Finder into Terminal to insert its actual path, then keep the quotation marks around the path. Do not remove them when the path contains spaces.
Use Terminal to Confirm the Port Is Listening
After approving the launch, use lsof to check example port 10808. Replace the number if your actual port differs. The local proxy entry point is established only when the v2rayN core process appears in LISTEN state.
lsof -nP -iTCP:10808 -sTCP:LISTENIf there is no output, return to v2rayN and check the local listening port and Core Type under “Settings” → “Parameters”, then review the core log. If another program is using 10808, quit it or select an unused port in v2rayN. Update the system proxy afterward as well; changing only one side is not enough.
Verification Order When the System Proxy Still Fails
System proxy issues are often mistaken for a dead node. The sensible order is to confirm that the core starts, verify that the local port exists, read the current macOS proxy state, and only then test an external request. This narrows the fault to the node, core, local port, or system settings.
scutil --proxyFocus on HTTPEnable, HTTPSEnable, SOCKSEnable, and their corresponding Proxy and Port fields. Enabled values are usually 1, the address should be 127.0.0.1, and the port should match v2rayN’s current setting. If every Enable field is 0, the system proxy is off. If the port is still an old value, the updated parameters were not written back to the system proxy.
- In v2rayN, first clear the system proxy, wait a few seconds, and then set the system proxy again to avoid stale configuration.
- Quit the browser completely and reopen it. Some running apps continue reusing old connections, so refreshing a page alone cannot verify the new proxy.
- Confirm the active network interface. Ethernet and Wi-Fi may have different proxy settings, so check the interface currently in use.
- Temporarily disable other network tools that modify the system proxy to prevent multiple programs from overwriting the proxy address and port.
- If the node test fails, check that the subscription updated successfully, that the node protocol is supported by the selected core, and that the system date and time zone are accurate.
For VLESS, VMess, Trojan, or Shadowsocks nodes, the system proxy layer still sees only a local HTTP, SOCKS, or mixed proxy port. The remote protocol does not appear directly in macOS’s proxy panel. Protocol parsing and transport are handled by the core selected in v2rayN, so a correct system proxy address cannot compensate for a failed core configuration.
Routing mode also affects what you observe. With rule-based routing enabled, some destinations may connect directly while others use the proxy. When troubleshooting installation and permissions, check the actual outbound used in the core log and test multiple destinations rather than judging the system proxy from one page alone.
Common Problems and Recovery Steps
Why does the prompt return after I clicked “Open Anyway”?
First confirm that you are launching the same v2rayN.app in Applications, not a freshly extracted copy in Downloads. If the path matches, use xattr to inspect the quarantine attribute. If it is absent, check whether each update replaced the app with a new bundle.
Can I change the network access choice after clicking Deny?
Yes. Open “System Settings” → “Network” → “Firewall” → “Options”, find v2rayN or the corresponding core, and change its incoming connection permission. Quit v2rayN and the core process, then start them again.
v2rayN says it is connected. Why does the browser still connect directly?
Check whether the current proxy mode has been written to the system proxy, then run scutil --proxy to verify the address and port. If the browser has its own proxy rules, make sure they are not bypassing macOS system settings.
What should I do when the log says the port is already in use?
Use lsof to identify the process holding the port. You can end the old core or choose another local port under “Settings” → “Parameters”. Restart the core afterward and set the system proxy again so both sides use the same port.
What if the main window opens but the core exits immediately?
First check whether “Settings” → “Parameters” → “Core Type” matches the node protocol, then inspect the first error in the log. Configuration parsing failures require checking node parameters; permission errors require checking the app directory and core files. Repeatedly launching the app will not fix either issue.
The full recovery path is: keep the app in a fixed location, approve it once through Privacy & Security, allow necessary network access, confirm that the core is listening, and point the system proxy to the same local port. Verify each step as you complete it; this is more effective than changing subscriptions, routing, DNS, and ports all at once.