The functionality of v2rayA depends on the V2Ray core, so the kernel needs to be installed.

v2rayA and v2ray do not yet support Packet Filter on macOS / FreeBSD, so transparent proxy cannot be enabled. For security reasons, this wiki will run v2rayA with non-root privileges.

The v2ray core of brew stays at version 4.45, but v2rayA needs the core of version 5.x. Be aware of this change if you choose to install manually.

Install with Homebrew

Please make sure Homebrew is installed and well working.


Add v2rayA Tap:

brew tap v2raya/v2raya

Install v2rayA:

brew install v2raya/v2raya/v2raya

v2ray5 will be installed as a dependent package of v2rayA, so that v2rayA will run correctly.

Start up

After the installation is complete, you can run v2raya --lite command in the terminal, or you can start the service:

brew services start v2raya

Manual installation

Create directory

These directories may already exist, please check before creating them.

Binary directory:

sudo mkdir /usr/local/bin/

Data files directory:

sudo mkdir -p /usr/local/share/v2ray/

Service file directory:

mkdir ~/Library/LaunchAgents/

Download v2rayA

Download the binaries for macOS from GitHub Releases or GitHub Action, then rename to v2raya and save it to /usr/local/bin/ .

For example:


sudo curl -L -o /usr/local/bin/v2raya


sudo curl -L -o /usr/local/bin/v2raya

Download V2Ray Core / Xray Core

Install V2Ray:
Install Xray:

After decompressing the compressed package, move the files in it to the corresponding directory:

sudo mv v2ray /usr/local/bin/
sudo mv *dat /usr/local/share/v2ray/

Permission settings

Give v2rayA and v2ray executable permissions:

sudo chmod 755 /usr/local/bin/v2raya
sudo chmod 755 /usr/local/bin/v2ray
sudo chmod 755 /usr/local/bin/v2ctl

If you encounter security restrictions of macOS, then you need to run the following command:

sudo xattr -d -r  /usr/local/bin/*

Create service files

Create a new service file and save it to ~/Library/LaunchAgents/


nano ~/Library/LaunchAgents/org.v2raya.v2raya.plist


<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "">
<plist version="1.0">

Start up

launchctl load ~/Library/LaunchAgents/org.v2raya.v2raya.plist

If you want to close the v2rayA service, replace the above command from load to unload . The logs can be viewed through the web pages.

Edit this page on GitHub

Last update on: Apr 13, 2023 19:32 +0800

Contributors: I404I zlicdt mt-gitlocalize