Install v2rayN on macOS: Unverified Developer Warning and Network Permissions

At a glance

Choose the right processor architecture before installing, then address Gatekeeper. Once the main window opens, verify a node through the local proxy, configure the system proxy, and enable TUN only if needed. This guide covers app launch approval, permission to change system proxy settings, and network extension approval separately. It’s for Mac users dealing with installation blocks, browsers that bypass the proxy, or TUN startup failures.

Choose the right installer: arm64 for Apple silicon, x64 for Intel

v2rayN is a desktop client for managing nodes, subscriptions, and routing settings. The proxy core it launches handles the actual connections. The installer architecture affects not only whether the main window opens, but also whether the bundled core can run. So seeing the interface doesn’t necessarily mean the entire runtime is working properly.

Choose a package based on the processor shown in About This Mac

Apple silicon Mac

Open the Apple menu → About This Mac and check the Chip field.
For Apple M-series Macs, choose the macOS arm64 package.
Don’t choose the x64 package just because macOS supports Rosetta; the core and helper components also need to match your architecture.

Intel Mac

About This Mac usually shows an Intel processor.
Choose the macOS x64 package; x86_64 is another label for the same architecture.
An arm64 package is not a suitable alternative for an Intel Mac.

Architecture and minimum macOS version are separate requirements. Even with the right package, check the macOS version required by the current release.

Go to the macOS download page from the download center. For a disk image, drag the app to Applications. For an archive, extract it fully and place the app as described in the release notes. Don’t run it from the archive preview, and don’t copy only the main app while leaving its dependencies behind. Before updating, quit the old process and back up your subscriptions, routing settings, and any other essential configuration.

“Developer cannot be verified”: Allow only apps from trusted sources

“Developer cannot be verified” and “Apple cannot check it for malicious software” are usually Gatekeeper launch checks, not node errors. Reimporting a subscription won’t fix them, and there’s no need to disable Mac security checks altogether. First verify the download source, make sure the file was fully extracted, and check the app name shown in the warning.

Confirm the app’s location

In Finder, open Applications and make sure you’re launching the newly installed v2rayN—not an old copy in Downloads or one still running from a mounted disk image.
Trigger the launch check

Double-click the app, read the warning, and dismiss it. Note its exact wording so you can distinguish a developer verification failure from an architecture mismatch or damaged file.
Open Security settings

Go to the Apple menu → System Settings → Privacy & Security. Scroll down to the Security section and check whether the blocked app and an Open Anyway button appear.
Approve the app once

Verify the app name, click Open Anyway, and authenticate as an administrator if prompted. In the next confirmation dialog, choose Open. Return to the app and check the main window and logs.

macOS 15 and later have stricter steps for opening unsigned or unnotarized software, so don’t assume that right-clicking the app in Finder and choosing Open will still approve it. Use the review option under Privacy & Security; older macOS versions may label this differently. Managed Macs may disable this action. Contact your device administrator rather than bypassing management policies.

Verify the local port before routing browser traffic through the system proxy

After v2rayN opens, import a trusted subscription, update the server list, and select a node. Then check the logs to confirm that the core has started. In the main window, open Settings → Parameter Settings and review the local listening configuration; field names vary by version. Confirm the listening address and port before troubleshooting the system proxy.

10808

Example HTTP proxy port used in the commands below

10809

Example alternative port to consider if there’s a port conflict

These ports are examples, not defaults guaranteed for every release. Before running the commands, replace them with the HTTP or mixed listening port enabled in Parameter Settings. If only a SOCKS listener is enabled, the HTTP proxy commands below won’t work as written. For local use, keep the listening address set to 127.0.0.1; don’t expose it on every network interface just to work around a permissions issue.

# Check whether the example port has a TCP listener
lsof -nP -iTCP:10808 -sTCP:LISTEN

# Specify the HTTP proxy explicitly instead of relying on macOS system proxy settings
curl --proxy http://127.0.0.1:10808 --connect-timeout 10 --max-time 20 -I https://example.com

example.com is only a connectivity test target; success doesn’t mean every website or routing rule is working. If the connection is refused, check the local listener first. For a proxy handshake error, verify the port type. If the local proxy connects but times out, check the core logs, node settings, and actual outbound route. A browser that keeps spinning doesn’t, by itself, indicate a system permissions issue.

Explicit proxy command works, browser doesn’t: Check whether the system proxy was set for the active network service and whether the browser uses its own proxy settings.
Explicit proxy command also fails: Check the core, node, and routing first; don’t add TUN on top.
Port is in use by another process: Identify the process, then decide whether to quit the conflicting app or change the listening port. If you change it, update the system proxy too.

System proxy or TUN: Choose the right traffic routing method

A system proxy isn’t a virtual network interface; it only affects apps that honor those settings. TUN routes traffic through a virtual interface and typically requires elevated permissions. It’s also more likely to conflict with other networking tools. For a first-time setup, start with the easier-to-observe system proxy path, then decide whether you need TUN.

Start with the system proxy

Recommended

In the v2rayN main window, choose Set System Proxy from the System Proxy menu. Some versions also offer this from the menu bar icon. The first time you change network settings, macOS may ask for administrator authentication. Afterward, check that the system proxy address and port are correct.

Best for: browsing, validating a new installation, and narrowing down issues on a desktop.

Enable TUN if needed

Once you’ve confirmed the node works, enable TUN in the client and follow the current version’s instructions for elevation or helper service setup. TUN routes traffic through the interface, but routing rules still apply; not every connection will use the proxy outbound.

Best for: apps that don’t honor the system proxy, or when you need a virtual interface to handle more traffic.

To check the system proxy, go to System Settings → Network → the active Wi-Fi or Ethernet connection → Details → Proxies. Check whether web proxy, secure web proxy, and SOCKS proxy are enabled, and confirm that their addresses and ports match the client. Before making manual changes, note the original settings—especially automatic proxy settings required by a workplace network.

# Check the current system proxy status
scutil --proxy

# List network service names; use the actual name in subsequent queries
networksetup -listallnetworkservices

# The following example uses a service named Wi-Fi
networksetup -getwebproxy "Wi-Fi"
networksetup -getsecurewebproxy "Wi-Fi"
networksetup -getsocksfirewallproxy "Wi-Fi"

These commands only check settings; they don’t change them. After switching Wi-Fi, connecting an Ethernet adapter, or changing network locations, the active network service may change, so check the proxy status again. Command-line tools in Terminal don’t necessarily read the macOS system proxy settings. That’s why the commands above specify a proxy explicitly, avoiding confusion between tool behavior and a client issue.

Network permissions: Extension approval and TUN elevation are different

There’s no single “allow network access” switch that fixes everything. Changing the system proxy, creating a TUN interface, accessing the local network, accepting incoming connections, and loading a network extension are controlled by different mechanisms. The exact implementation in v2rayN varies by release and core combination; seeing “TUN” doesn’t automatically mean a network extension must be installed.

Warning or symptom	Where to check	What to look for
Authentication required to change proxy	System authentication dialog after a client action	Confirm the request comes from the app you’re using. After authentication, check that the proxy settings were actually applied.
TUN creation fails or permission denied	v2rayN logs and helper service settings for the current version	Look for messages such as permission denied or operation not permitted; configure permissions according to the release notes.
A network extension approval prompt appears	On macOS 15: System Settings → General → Login Items & Extensions → Network Extensions	Approve only the item associated with the component you just installed. Other macOS versions may show the approval option under Privacy & Security.
Can’t access local network devices	On macOS versions with this option: Privacy & Security → Local Network	This permission is for local network access; it doesn’t authorize internet proxying or replace TUN elevation.
Prompt asks whether to allow incoming connections	System Settings → Network → Firewall → Options	Permission for incoming connections is different from ordinary outbound proxy traffic. If you’re using the app only on this Mac, don’t widen the listening scope because of this prompt.

Before enabling TUN, temporarily quit other networking tools that change the default route, DNS, or virtual interfaces. Keep only one traffic-routing method active at a time. If TUN still fails after authentication, save the full error context from the first startup attempt instead of repeatedly entering your password. On managed devices, neither administrator authentication nor in-app settings can replace approval under the organization’s policies.

Quitting and updating: Check for lingering proxy settings and configuration changes

If your connection drops after quitting, the system proxy may still point to a local port that’s no longer running. Before quitting normally, clear the system proxy and disable TUN in the client. If the app exits unexpectedly, check the active network service’s proxy settings in System Settings and restore the values you recorded before setup. If you use automatic proxy configuration, check that it hasn’t been changed either.

Main window won’t open: Note the exact macOS warning and recheck the architecture, minimum system version, and Gatekeeper approval status.
Main window opens, but the core exits: Check the core architecture, execution permissions, configuration errors, and port conflicts. Save the logs before deciding whether to extract the installer again.
Proxy command works, but an app doesn’t: Check whether the app honors the system proxy or has its own proxy settings before switching to TUN.
Domains fail after enabling TUN: Use DNS and routing logs to trace name resolution. Don’t assume every DNS failure is a permissions issue.
Behavior changes after an update: Compare the listening port, selected core, and routing settings from before and after the update. Don’t overwrite the entire new configuration with old files without checking them first.

Troubleshooting notes should include the macOS version, processor architecture, v2rayN version, selected core, current proxy mode, and time of the error. Before sharing logs, remove subscription URLs, node passwords, user identifiers, and other sensitive parameters. This helps distinguish installation blocks from core startup and routing issues, and avoids changing multiple settings at once without a clear baseline.