Install v2rayN on macOS: Fix “Unidentified Developer” Warnings and Grant Network Permissions

Choose an Installer and Install the App

Open the Apple menu in the top-left corner and select “About This Mac.” If you see “Chip” followed by an Apple chip model, choose macOS ARM64. If you see “Processor” and an Intel model, choose macOS x64. Don’t guess the architecture from the installer’s file size, and don’t try to launch a Windows installer on macOS.

Before installing, note your macOS version in “About This Mac” and compare it with the installer’s minimum system requirements. An unsupported macOS version and a Gatekeeper block are different issues: “This application can’t be opened on this Mac” doesn’t necessarily mean you need to bypass a security restriction. Check the architecture and system requirements first, then read the full alert.

1. Check Your Mac’s Architecture

   Open the Apple menu → “About This Mac” and choose ARM64 or x64 based on the chip information. Get the installer from the site’s download page.

2. Open the Disk Image

   Double-click the downloaded DMG file, then locate the v2rayN app in the disk window. If the disk image won’t mount, download it again rather than changing your security settings.

3. Move It to Applications

   Drag v2rayN into Finder’s “Applications” folder. Wait for the copy to finish, eject the disk image, then launch the app from “Applications.”

4. Keep Installation Details

   Note the app version from its “About” page, your macOS version, and the installer architecture. Including these details in a bug report makes troubleshooting much easier than simply saying the app won’t open.

Don’t run the app indefinitely from a disk image or your Downloads folder. Keeping it in a consistent location helps with updates, permission checks, and login item management. Quit the old process before updating. If the old version has TUN enabled, turn it off and clear the system proxy before replacing the app.

How to Allow an “Unidentified Developer” App

Gatekeeper checks an app when you try to launch it. If the alert says the developer can’t be verified or the app can’t be checked for malicious software, the core usually hasn’t started listening on a port yet. Changing servers, subscriptions, or DNS won’t resolve a launch block.

1. Try Launching the App

   In “Applications,” double-click v2rayN, read the warning, and close it. Continue only if you’ve confirmed the app’s source.

2. Open Security Settings

   Go to Apple menu → “System Settings” → “Privacy & Security,” then scroll down to “Security” and find the record for the app that was just blocked.

3. Allow This App to Open

   Confirm the app name in the record, click “Open Anyway,” authenticate as an administrator if prompted, then click “Open” in the confirmation dialog.

4. Try Again

   Return to “Applications” and launch the app again. If there’s no matching record, trigger the warning once more and check again. On a managed device, contact your administrator.

Finder’s right-click → “Open” behavior varies across macOS versions, so it isn’t a reliable fix. Check for an explicit approval under “Privacy & Security” first. On a managed device, policy may disable “Open Anyway”; repeatedly entering an administrator password won’t override it.

System Proxy or TUN: Choose How to Route Traffic

Opening v2rayN doesn’t mean all your apps’ traffic is being proxied. The system proxy sets proxy details for the current network service, but whether an app uses them depends on the app. TUN routes traffic through a virtual network interface and also involves routing, DNS, and permissions. When troubleshooting for the first time, test these methods separately.

If the client asks to change network settings, approve only when you’ve just performed the corresponding action and the authentication dialog clearly identifies the app or a component you recognize. Configuring the system proxy doesn’t install a network extension, and connecting to the internet doesn’t require “Full Disk Access” or “Accessibility” permissions.

• Check the system proxy: Go to “System Settings” → “Network” → your current Wi-Fi or Ethernet connection → “Details” → “Proxies.” Note the addresses and ports for HTTP, HTTPS, or SOCKS.
• Check the local address: the local proxy usually uses 127.0.0.1. The port must match the one v2rayN is actually listening on. Don’t copy a number just because it appears in a tutorial.
• Restore settings before quitting: In v2rayN, select “Clear system proxy,” then quit the client. If the app quits unexpectedly, return to the system settings page above and remove any leftover local proxy settings.

Identify Network Extensions and Other Network Permissions

“Network extension,” “VPN configuration,” “Local Network,” and administrator authentication are different permission types. Check the wording of the system alert, then open the relevant settings. Different v2rayN releases and run modes may use different traffic-routing methods; if you’re using only the system proxy, it’s normal not to see a network extension prompt.

If macOS asks to “Add VPN Configurations,” check the app name before deciding whether to allow it. You can search for “VPN” in System Settings afterward to review the entry. Don’t weaken app launch security to troubleshoot a regular proxy connection. If your connection drops after enabling TUN, turn TUN off, clear the system proxy, and confirm your regular network works again. Then check the client logs for permission, routing, or DNS errors.

• No permission dialog appeared: First check whether you enabled a feature that actually needs extra permissions, rather than just opening the app window.
• Still failing after approval: Quit and relaunch the app, then check the core logs. “Permission denied” and “Address already in use” require different fixes.
• macOS requires a restart: Save your work, then restart as prompted. Relaunching the client alone may not complete approval for a system component.

Check Your Connection After the First Launch

Once permissions are sorted out, import a configuration you know works. In v2rayN, open “Subscription Groups” → “Subscription Group Settings,” add a name and subscription URL, and save. Then open the “Subscription Groups” menu and update the group. Menu labels may vary slightly by version; the important steps are to save the group first, then fetch its contents. Saving a URL alone doesn’t confirm that any servers were imported.

VMess and VLESS are protocol names used in configurations, not macOS permission types. A subscription URL fetches a list of configurations; an individual share link describes one configuration. Use the appropriate import option for each. Preserve the TLS, SNI, transport, and path values provided by the subscription rather than changing them to troubleshoot installation.

1. Check the list first: After updating, you should see configuration entries. If the list is empty, check the subscription response, group filters, and update logs. Don’t start by approving a network extension.
2. Then check the core: Select a configuration and set it as the active server. Check the logs for core startup failures, missing files, or a port conflict. A running status in the interface isn’t a substitute for checking the logs.
3. Check the listening port: Go to “Settings” → “Parameter Settings” and check the local listening port options, then compare them with the system network proxy page. The 10808 in the command below is only an example; replace it with the actual port before running the command.
4. Test access: First, use the system proxy to visit an HTTPS site you normally use, then check for a matching connection log. A successful latency test doesn’t mean every app is using the proxy.

lsof -nP -iTCP:10808 -sTCP:LISTEN
scutil --proxy

The first command checks whether a process is listening on the TCP port. The process name and PID in the output can help identify it. If there’s no output, verify the port number first, then check whether the core is running. The second command reads the current system proxy settings. Look for fields that are actually present, such as HTTPEnable, HTTPSProxy, and HTTPSPort. Don’t rely on a setting being 1 alone; make sure the address and port are both correct.

Common Installation and Permission Questions