V2Ray runs on a Mac, but the project itself gives you only a command-line program. To use it day to day you need two more things: a client app with a window, and a server to connect to.

The details below come from each project's own pages and from Apple's support pages, read 19 November 2026. We did not install these clients ourselves, so nothing below is a test result.

What you need to run V2Ray on a Mac

There are three parts, and the project supplies only the first:

  • A core. This is the program that speaks the protocols. This guide deals with two: V2Ray itself, maintained by the V2Fly project, and Xray-core, which began as a fork of it. Two other guides explain the protocols: what V2Ray is and what VLESS is.
  • A client app. This is a program with a window that stores your servers, starts the core and sends your Mac's traffic to it.
  • A server. V2Ray is software and comes with no servers. Someone has to run one, whether that is you or a provider. Clients take its details as a share link, a QR code or a subscription address.

What the projects publish for macOS

V2Ray's installation guide offers two ways onto a Mac: download the zip file and unpack it to get an executable called v2ray, or install it with Homebrew (brew install v2ray). Either way, the guide's next step is to "run V2Ray in command line" (V2Fly installation guide).

Xray works the same way. Its official releases support macOS on both Intel (amd64) and Apple silicon (arm64). You unpack a zip file to get an executable called xray, or you run brew install xray (Xray installation guide). The latest release of each core carries one macOS file for Intel and one for Apple silicon.

Neither project ships a Mac app with a window. A core alone is enough if you are comfortable writing its configuration file by hand. Otherwise you need a client, and the Xray guide points to third-party ones.

V2Ray clients for Mac

Xray-core's README keeps a list of graphical clients. Under "macOS arm64 & x64" it names Happ, V2rayU, V2RayXS, Furious, OneXray, GoXRay, AnyPortal, v2rayN, GenyConnect and INCY, and under "iOS & macOS arm64 & tvOS" it names Happ, Streisand, OneXray and INCY (Xray-core on GitHub, read 19 November 2026). The README lists them without rating them.

v2rayN

v2rayN's README describes it as "A GUI client for Windows, Linux and macOS" with support for Xray, sing-box and other cores. It lists macOS builds for Intel (x64) and Apple silicon (arm64), carries the GPL-3.0 license, and says its release files are signed with GPG so that you can check a download is authentic (v2rayN on GitHub). The project's wiki sets the minimum at macOS 13.6 and says the download already includes the Xray, sing-box and mihomo cores (release files introduction, in Chinese). Its latest release is dated October 11, 2026.

The same wiki page says the macOS installer is not signed, so macOS reports the app as damaged. The section on macOS warnings below covers what that means.

V2rayU

V2rayU is a client made for the Mac. Its repository description, in Chinese, says it is built on the V2Ray core, written in Swift, and supports Trojan, VMess, Shadowsocks and SOCKS5 servers, with subscriptions and import from a QR code or the clipboard (V2rayU on GitHub). The latest release, dated November 8, 2026, comes as one .dmg file for Intel Macs and one for Apple silicon (V2rayU releases).

The repository's front page carries no documentation today, and the release notes are in Chinese.

Happ and Streisand

Streisand and Happ are iPhone and iPad apps that the Xray README also lists for Apple silicon Macs. Apple's listing data for the US App Store lists a Mac among the devices Happ supports, and only iPhone, iPad and iPod touch models for Streisand (checked 19 November 2026). Both are free to download on the US App Store (Apple's listing data, checked 19 November 2026). Streisand's listing names VLESS with Reality, VMess, Trojan and Shadowsocks among its protocols. Happ's listing says the app "does not sell or provide VPN services" and that users must set up their own servers.

Apple reviews each App Store app before accepting it and signs it, and the warnings described below are for software from outside the App Store (Apple's guide to opening apps safely on a Mac).

How to set up V2Ray on a Mac

The steps below use v2rayN, because its wiki documents them. Other clients have their own menus.

  1. Get your server details. You need a share link, a QR code or a subscription address from whoever runs your server.
  2. Download the build for your chip. On the project's releases page, take v2rayN-macos-arm64.dmg for Apple silicon or v2rayN-macos-64.dmg for an Intel Mac. To see which you have, open About This Mac from the Apple menu: an Apple silicon Mac shows a line labeled Chip, and an Intel Mac shows a line labeled Processor (Apple's list of Mac computers with Apple silicon).
  3. Install it and open it. macOS will object, because the installer is not signed. Read the next section before you go further.
  4. Import the server. Copy the share link and use the client's command for importing from the clipboard. v2rayN reads the clipboard, adds an address that begins with https as a subscription, and adds a standard share link as a server (v2rayN wiki, in Chinese).
  5. Choose how traffic reaches the core. With the system proxy option, v2rayN forwards the traffic of some software, such as browsers, to the core (system proxy and routing, in Chinese). The other option is Tun mode, which the wiki says needs administrator rights.
  6. Connect and check. Start the server entry, then confirm that your public IP address has changed. Our guide to checking whether a VPN is active shows how.

"Apple could not verify" and "app is damaged": the macOS warnings

macOS checks software that comes from outside the App Store. A technology called Gatekeeper looks for a Developer ID signature and, since macOS Catalina, for notarization, which means Apple has checked the software for known malware. When your Mac cannot verify an app, it shows an alert and does not open it (Apple's guide).

v2rayN is an example. Its wiki says the macOS installer is not signed, that macOS will report the app as damaged, and that after installing you should run xattr -cr /Applications/v2rayN.app in Terminal. That command removes every extended attribute, which is metadata stored with a file, from the app and the files inside it. In the xattr manual page, -c clears all attributes and -r applies the command to everything in a folder.

Apple documents its own route for an app it cannot verify. Try to open the app once, then open System Settings, click Privacy & Security, scroll down and click Open Anyway. Apple's guide attaches a condition: do this only if you are certain the app comes from a trustworthy source and has not been tampered with, because software that is not signed and notarized may expose your Mac to malware.

So download only from the project's own releases page, and check the file. v2rayN signs its release files with GPG, which its README says helps prevent hijacking by a mirror, an internet provider or a CDN. If that is more risk than you want, use an App Store client or a VPN app.

The warning can name xray and not the client. v2rayN's wiki says its packages include the Xray, sing-box and mihomo cores, so the file macOS objects to can be a core.

The alternative: a VPN app with XRay built in

If you would rather not run a server or work around Gatekeeper, the alternative is a VPN app whose maker runs the servers and builds the protocol in. Tegant VPN is our own app, and it works this way.

Tegant for Mac is on the Mac App Store. On the main screen you switch from WireGuard to XRay, pick a server and connect. Tegant's XRay option runs VLESS with Vision and Reality, Trojan over TLS, VLESS with XHTTP over TLS, and VLESS with XHTTP over Reality.

XRay is part of Tegant Premium on iPhone, iPad, Mac and Android, and it is available in 15 of Tegant's 18 server countries; France, Italy and Spain are WireGuard only. The free tier, where it is available, is WireGuard only. Tegant doesn't provide configuration files, so you use its servers through the app and can't move them to another client. No VPN can guarantee access on every network, and that includes ours.

Rules on VPNs differ from country to country and change often, so check the current law where you are. Our guide to how VPN rules differ by country has more.

Common problems

  • The app won't open, or macOS says it is damaged. That is Gatekeeper. See the section on macOS warnings above.
  • You downloaded the wrong build. Apple silicon Macs take the arm64 file and Intel Macs take the 64 file. About This Mac tells you which Mac you have.
  • A VMess server won't connect. Check the Mac's clock first. VMess depends on the system time, and the Xray documentation asks for it to be within 120 seconds of the real time (VMess documentation).
  • The browser works and other software doesn't. v2rayN's wiki says the system proxy carries the traffic of some software, such as browsers. For the rest, the client's other option is Tun mode.
  • The system proxy isn't set. v2rayN's FAQ says the macOS build sets the system proxy by calling a script, that the script can fail on some setups, and that the failure is recorded in the logs in its guiLogs folder (v2rayN FAQ, in Chinese).

If the trouble is with a VPN app and not a V2Ray client, see why your VPN is not working.

V2Ray on Mac questions

Is there an official V2Ray app for Mac?

No. The V2Ray project publishes the core, which is a command-line program, and its macOS instructions end with running it from the command line. The apps with windows come from other developers.

Does V2Ray work on Apple silicon Macs?

Yes. The latest V2Ray and Xray releases each include a macOS file for arm64, the Apple silicon architecture, and v2rayN and V2rayU each publish an Apple silicon .dmg file (release pages read 19 November 2026).

Can I install V2Ray on a Mac with Homebrew?

Yes. Each project's installation guide gives the command: brew install v2ray for V2Ray and brew install xray for Xray. Homebrew installs the command-line core, with no window or menu.

Is V2Ray free on a Mac?

The software is. V2Ray, Xray-core and v2rayN are open source, under the MIT, MPL-2.0 and GPL-3.0 licenses. A server is not free to run: someone rents and maintains it, whether that is you or a provider.


Tegant VPN supports WireGuard and, with Premium, XRay, so you can switch protocols depending on your network. Learn more about Tegant VPN.