2026-08-14 · Platform Notes · About 10 minutes

v2rayN Won’t Open on macOS After Installation? Step-by-Step Fixes for Unverified Developer and Network Permissions

Step-by-step macOS fixes for “developer cannot be verified,” apps moved to the Trash, and network extension permission prompts when enabling system proxy or TUN mode.

Quick Overview

This guide is for users who have downloaded v2rayN but are blocked by macOS security alerts, an architecture mismatch, or network permissions. Check the installer and CPU architecture first, then allow the app in Privacy & Security, and finally verify system proxy, TUN, local network, and firewall permissions.

First Identify Which Stage Is Failing

“Won’t open” can mean three different things. First, macOS may immediately show “cannot verify the developer” or “cannot confirm it is free of malware” after a double-click. That is Gatekeeper checking an app being launched for the first time. Second, macOS may say the app is damaged or will be moved to the Trash, usually because the download is incomplete, the archive was extracted incorrectly, quarantine attributes remain, or the app architecture is wrong. Third, the main window may open but networking may fail after enabling the system proxy or TUN. In that case, check the proxy port, core logs, and system permissions instead of reinstalling repeatedly.

Start by checking the device architecture. Open the Apple menu in the upper-left corner, choose “About This Mac,” and check “Chip” or “Processor.” Choose an arm64 build for Apple silicon and an x64 build for Intel. With the wrong architecture, the icon may bounce briefly and quit, or Terminal may report that the architecture cannot be executed.

Allow the App in Privacy & Security

Recommended

For the “developer cannot be verified” alert. Try opening the app with a right-click first, then confirm this launch in System Settings.

Best for: first launch when the archive extracts normally

Download and Extract Again

For incomplete installers, extracted folders missing core files, or apps that are moved to the Trash every time.

Best for: abnormal file size or incomplete app contents

Check Network Permissions

For cases where the interface opens but the system proxy, TUN, or local network access does not work.

Best for: logs show the core started but websites still cannot connect

Standard Steps for an Unverified Developer

macOS adds a quarantine flag to apps downloaded from a browser. When v2rayN is opened for the first time, the system may offer only a “Cancel” button. Do not keep double-clicking, and do not weaken security for the entire device. Explicitly allow this app once.

  1. Move It to Applications

    After extraction, drag v2rayN.app into the “Applications” folder. Do not run it from the archive preview window, a download cache, or a read-only disk image.

  2. Open with a Right-Click

    In Finder’s “Applications” folder, locate v2rayN, hold Control while clicking its icon, and choose “Open.” This dialog usually includes an additional “Open” button for confirmation.

  3. Open Privacy Settings

    If the app is still blocked, open “System Settings” → “Privacy & Security,” scroll down to the “Security” section, and find the v2rayN entry that was just blocked.

  4. Click Open Anyway

    Click “Open Anyway,” enter an administrator password, or complete device authentication. macOS will show another confirmation dialog; verify the app name and choose “Open.”

  5. Configure the Core

    After reaching the main interface, open “Settings” → “Parameter Settings” → “Core Type.” For everyday use with VLESS, VMess, or Trojan nodes, select Xray and save the settings.

The approval usually applies only to the current app version and location. After updating v2rayN, macOS may ask again if the app bundle has changed. Keeping the app in the “Applications” folder helps prevent repeated checks caused by path changes.

How to Check “Damaged” or “Moved to Trash” Alerts

“App is damaged” does not necessarily mean the program itself is faulty. Common causes include an incomplete archive, a third-party extractor changing app-bundle permissions, choosing the wrong arm64 or x64 build, or quarantine attributes not being handled correctly by the system UI. Delete the current copy, download a complete archive for the correct architecture, and extract it with Finder’s built-in tool.

After extracting again, drag the app into “Applications” and open it with a right-click. If “Open Anyway” does not appear in Privacy & Security, and the file source and architecture are confirmed, use Terminal to check whether the app still has a quarantine attribute.

xattr -l "/Applications/v2rayN.app"
xattr -dr com.apple.quarantine "/Applications/v2rayN.app"

The first line only reads extended attributes. If the result includes com.apple.quarantine, the second line removes the quarantine attribute from v2rayN.app and its internal files. Then open it again with a right-click. Keep the double quotes around the path; if the app name or location differs, replace the path with the actual location shown in Finder.

Launch File Baseline

Installation Location
/Applications/v2rayN.app
Apple Silicon
arm64
Intel
x64
First Launch
Control-click → Open

Match the architecture and use a fixed path before handling quarantine attributes.

Core Startup Baseline

Core Type
Xray
Local Address
127.0.0.1
Common Mixed Port
10808
Log Level
warning or info

Users can change the port; during troubleshooting, use the current value shown in Parameter Settings.

System Proxy and TUN Permissions Are Different

System proxy and TUN mode cover different traffic. The system proxy writes HTTP, HTTPS, and other proxy settings to the current network service, allowing apps that support system proxy settings to connect to v2rayN’s local listening port. TUN creates a virtual network interface and can handle more traffic from apps that ignore system proxy settings, so it usually requires higher privileges.

Choose a Mode Based on Traffic Coverage

System Proxy
  • Start the Xray core first
  • The local listener commonly uses 127.0.0.1:10808
  • Suitable for browsers and desktop apps that read system proxy settings
  • Restore the system proxy before closing v2rayN
TUN Mode
  • Creates a virtual network interface
  • Administrator authentication may be required the first time
  • macOS may ask to approve a VPN configuration or network filtering permission
  • Routing conflicts may occur when other VPN configurations are active

For the first setup, verify that the system proxy works before enabling TUN separately. This makes it easier to determine whether the problem is the node, the core, or system permissions.

When using only the system proxy, you typically do not need to approve a network extension. If websites do not open, first check the v2rayN log to confirm that the core is listening on a local port. Then open “System Settings” → “Network” → current network service → “Details” → “Proxies.” The HTTP or HTTPS proxy address should be 127.0.0.1, and the port must match the current v2rayN setting.

When enabling TUN, macOS may ask to add a VPN configuration, change network settings, or allow a background item. Verify the name before approving. Then open “System Settings” → “Network” → “VPN & Filters” and confirm that the corresponding configuration has not been disabled manually. If blocked system software appears at the bottom of Privacy & Security, allow it first and restart v2rayN.

Handle Network Permission Prompts One by One

macOS may separately ask about local network access, incoming connections, VPN configuration, and background operation. These permissions control different things. Local Network access mainly affects connections to routers, NAS devices, or other LAN services. Firewall incoming connections control whether other devices can initiate connections to this Mac. VPN configuration is related to TUN traffic capture.

  1. Check Local Network Access

    Open “System Settings” → “Privacy & Security” → “Local Network.” If you need to access LAN nodes or services, make sure the switch for v2rayN is enabled.

  2. Check the Firewall

    Go to “System Settings” → “Network” → “Firewall” → “Options.” Allow incoming connections for v2rayN only when LAN devices need to connect to this Mac; local use through 127.0.0.1 normally does not require external incoming access.

  3. Check the VPN Configuration

    Go to “System Settings” → “Network” → “VPN & Filters” and confirm that the TUN-related configuration exists and is enabled. During testing, disable other configurations that also take over the default route.

  4. Verify the Listening Port

    Check the local port in v2rayN’s Parameter Settings. If it is 10808, the browser or system proxy must also use 10808; do not keep using a port from another client.

  5. Restart the Core

    After saving the permission and port settings, stop the current core and start it again. If nothing changes, quit v2rayN and reopen it so macOS reloads the network configuration.

To confirm whether a port is listening, open Terminal and run the command below. A listening entry for v2rayN or its core process means the local endpoint has been established; no output means you should return to the core log and find the startup failure.

lsof -nP -iTCP:10808 -sTCP:LISTEN

When another process occupies the port, the log usually includes bind, address already in use, or listen failed. Stop the old process using that port, or switch to an unused port such as 10818 in “Settings” → “Parameter Settings.” Update the system proxy settings to match.

Troubleshooting Order When the App Opens but Has No Internet

Opening the main interface only proves that the graphical app passed the system check. It does not mean the core, nodes, or proxy settings are working. Troubleshoot in this order: core startup → local port → node connection → system routing → routing rules. Avoid changing multiple variables at once.

Clicked System Proxy but Websites Still Connect Directly?

First confirm in the log that the core has started. Then go to “System Settings” → “Network” → current network → “Details” → “Proxies,” and verify that the address is 127.0.0.1 and the port matches v2rayN’s Parameter Settings.

Internet Stops Working Immediately After Enabling TUN?

Disable TUN and restore the system proxy for testing. Then check the configuration status under “VPN & Filters,” temporarily disable other items that take over the default route, and look for permission or virtual-interface creation errors in the log.

Log Says Port 10808 Is Already in Use?

Run lsof -nP -iTCP:10808 -sTCP:LISTEN to find the process using the port. Stop the leftover core, or change the local port to 10818 and update the system proxy port as well.

Subscription Updates Successfully but Every Node Times Out?

Confirm that “Settings” → “Parameter Settings” → “Core Type” is compatible with the node protocol, then select one node and run a real connection test. If only some nodes fail, replace those nodes first instead of resetting system permissions.

Regular Websites Stop Opening After You Quit?

Open v2rayN again, restore the system proxy, and then quit. You can also open the “Proxies” page for the current network service and disable any HTTP, HTTPS, or SOCKS proxy still pointing to 127.0.0.1:10808.

Routing rules can also make “some websites fail to open.” Rules are matched from top to bottom, and the specified outbound is used after a match. If a custom rule sends a target domain to an invalid outbound, access will fail even when all system permissions are correct. Temporarily switch to a simpler global test mode to verify the node, then restore rule-based routing and check domain, IP, and process rules one by one.

Download V2Ray Client