# Step 1: Getting Qv2ray Distribution

To get started with Qv2ray, you should first obtain a release of Qv2ray. We offer many distribution methods, you can choose according to your preference.

# GitHub Releases Binary

Downloading stable release binary from Qv2ray GitHub Release (opens new window) is favored for Windows and macOS users. This is also suitable for Linux users where Qv2ray is not officially packaged in their distros, since they can use our AppImage releases.

Do as the follows:

Open Qv2ray GitHub Release Page (opens new window) in a web browser.
Choose a version from the releases. Or, optionally, you may use the Latest Stable Release (opens new window).
Choose in Assets according to your platform and download it! For example:
- For Windows Users:
  - Windows 10/8.1/7: Qv2ray.VERSION.Windows-x64/x86.7z (Archive) or Qv2ray.VERSION.win32/64.exe (Installer).
  - Windows 2003/XP/2000/ME/98/...: NOT SUPPORTED (since Qt does not support them);
- For Linux 64bit Users: Qv2ray.VERSION.linux-x64.AppImage.
- For macOS Users:
  - macOS 10.14 and later: Qv2ray.VERSION.macOS-x64.dmg;
  - macOS 10.13: qv2ray-legacy.dmg (if any);
  - macOS 10.12 and before: NOT SUPPORTED.
- For Ubuntu 19.04 / Debian 10 (or greater): ~~qv2ray_VERSION_amd64.deb~~ (Moved to Qv2ray Debian Repository (opens new window) since v2.6.1)
- For Arch Linux Users：qv2ray-VERSION-1-x86_64.pkg.tar.xz

Where VERSION is the version of that release.

Notes for Linux AppImage users

Although we have bundled glibc and some basic C++ libraries into the AppImage package to support some old but supported distros, moving yourself to a newer version of Distro/OS is strongly recommended.

Notes for Windows ARM64 users

Windows 10 on ARM users can use Qv2ray.VERSION.Windows-x86.7z (archive) or Qv2ray.VERSION.win32.exe (Installer) directly, since the operating system has a built-in compatibility layer for x86 architecture.

# GitHub Actions Artifact

If you are fed up with the functionalities of stable versions and willing to try out new features in development, you may download artifacts from GitHub Actions:

Open Qv2ray GitHub Actions Page (opens new window) in your web browser.
Choose a recent and successful (displayed as ✔️) build and click on it. You should be taken to the detail page of that GitHub Build. Here's an example (opens new window).
Click on Artifacts drop-down menu to expand it, and then choose binaries according to your platform.

TIP

You must login GitHub first to access GitHub Actions.

# Download From a package manager

# Debian, Ubuntu and their derivatives

Install the relevant tools.

sudo apt install gnupg ca-certificates curl

# Debian Stable install stable version of Qv2ray

Adding keys (you can optionally use FastGit to speed up adding keys)

curl -sSL https://qv2ray.net/debian/pubkey.gpg | sudo apt-key add -
# curl -sSL https://raw.fastgit.org/Qv2ray/debian/master/pubkey.gpg | sudo apt-key add -

Add software repositories (FastGit accelerated repositories can be enabled on demand)

echo "deb https://qv2ray.net/debian/ stable main" | sudo tee /etc/apt/sources.list.d/qv2ray.list
# echo "deb [arch=amd64] https://raw.fastgit.org/Qv2ray/debian/master/ stable main" | sudo tee /etc/apt/sources.list.d/qv2ray.list

Install Qv2ray

sudo apt update; sudo apt install qv2ray

# Debian Stable install the development version of Qv2ray

The development version for Debian supports AMD64, ARM64 and MIPS64EL architectures, and can be used on armbian.

Adding keys (optionally using FastGit to speed up adding keys)

curl -sSL https://qv2ray.net/debian-dev/pubkey.gpg | sudo apt-key add -
# curl -sSL https://raw.fastgit.org/Qv2ray/debian-dev/master/pubkey.gpg | sudo apt-key add -

Add software repositories (FastGit accelerated repositories can be enabled on demand)

echo "deb https://qv2ray.net/debian-dev/ stable main" | sudo tee /etc/apt/sources.list.d/qv2ray-dev.list
# echo "deb https://raw.fastgit.org/Qv2ray/debian-dev/master/ stable main" | sudo tee /etc/apt/sources.list.d/qv2ray-dev.list

Install Qv2ray

sudo apt update; sudo apt install qv2ray

# Debian Unstable

As a user of the unstable branch, we trust that you have the ability to add the corresponding repositories by referring to the stable version information. the Unstable branch repositories are codenamed unstable.

# Ubuntu and its official derivatives install the stable version of Qv2ray

The following commands are run in bash, or if you are using another shell, please run bash in the terminal first. *

Add a key (you can optionally use FastGit to speed up adding keys)

curl -sSL https://qv2ray.net/debian/pubkey.gpg | sudo apt-key add -
# curl -sSL https://raw.fastgit.org/Qv2ray/debian/master/pubkey.gpg | sudo apt-key add -

Add software repositories (FastGit accelerated repositories can be enabled on demand)

echo "deb https://qv2ray.net/debian/ `lsb_release -cs` main" | sudo tee /etc/apt/sources.list.d/qv2ray.list
# echo "deb https://raw.fastgit.org/Qv2ray/debian/master/ `lsb_release -cs` main" | sudo tee /etc/apt/sources.list.d/qv2ray.list

Install Qv2ray

sudo apt update; sudo apt install qv2ray

# Ubuntu and its official derivatives install the development version of Qv2ray

The following commands are run in bash, or if you are using another shell, run bash in the terminal first. *

Add a key (you can optionally use FastGit to speed up adding keys)

curl -sSL https://qv2ray.net/debian-dev/pubkey.gpg | sudo apt-key add -
# curl -sSL https://raw.fastgit.org/Qv2ray/debian-dev/master/pubkey.gpg | sudo apt-key add -

Add software repositories (FastGit accelerated repositories can be enabled on demand)

echo "deb https://qv2ray.net/debian-dev/ `lsb_release -cs` main" | sudo tee /etc/apt/sources.list.d/qv2ray-dev.list
# echo "deb https://raw.fastgit.org/Qv2ray/debian-dev/master/ `lsb_release -cs` main" | sudo tee /etc/apt/sources.list.d/qv2ray- dev.list

Install Qv2ray

sudo apt update; sudo apt install qv2ray

# Arch Linux-based distros

# Install directly from `archlinuxcn`

We have made ourselves into archlinuxcn repository. If you are already using it, simply type in your terminal:

sudo pacman -Syy qv2ray # or qv2ray-dev-git, see below.

And that shall be done.

TIP

You may also want to install v2ray package to use system V2Ray core.

Attention to Manjaro Hitchhikers on Arch Linux CN

Manjaro will delay Arch Linux's package changes. When there is a breaking ABI change in upstream, Arch Linux CN will prioritize Arch users instead of those of Manjaro. Manjaro users of Arch Linux CN should always be aware of and bear all consequences caused by the delayed update of its official source, including issues like symbol lookup error and etc. If you insist on using it, please do not submit it to either Qv2ray or Arch Linux CN as a bug in any way. For those who don't want trouble, please use AppImage / Snapcraft versions instead.

This nag will be removed whenever something like "Manjaro CN" is founded and officially take the workload of packaging Qv2ray for its users.

# Download from AUR, using an AUR Helper

You may acquire officially maintained PKGBUILD file from AUR (Arch User Repository, AUR (en) - Home (opens new window)), which will instruct the build process of Qv2ray.

You may use an AUR helper such as yay, yaourt, pikaur and so on to automatically handle the build process of AUR packages.

NOTE

The following example is utilizing yay. For other AUR helpers, check the usage in respective documentations.

First, you may try searching qv2ray in AUR:

$ yay -Ss qv2ray
aur/qv2ray-dev-git 1.99.4.r47514d2-1 (+2 0.98%)
     Qt cross platform v2ray GUI client (Dev branch build release)
aur/qv2ray 1.3.8.0-1 (+4 1.23%)
     Qt cross platform v2ray GUI client

Then, choose the adequate version of Qv2ray to install. There are two versions available:

Stable version, with package name qv2ray. This package is built from the master branch of Git repository, and shall be stable enough for cautious users.
Development version, with package name qv2ray-dev-git. This package is built from the dev branch of Git repository. Along with the newest features and improvements, there are potential risks for using an unstable distribution.

Choose according to your actual situation. Here, we choose to install qv2ray-dev-git:

$ yay -S qv2ray-dev-git

Qv2ray will be ready to use after finishing the command.

# Download from AUR, the hard way

You may not want to use an AUR helper to install Qv2ray from AUR. Then take a look at the following example.

# 1. Clone the AUR repository (`qv2ray-dev-git` as an example):
$ git clone https://aur.archlinux.org/qv2ray-dev-git.git

# 2. Enter `PKGBUILD` folder:
$ cd qv2ray-dev-git

# 3. Build Qv2ray:
$ makepkg -sf

# 4. Install the generated package after building:
$ sudo pacman -U qv2ray-dev-git-v1.99.4.2550-1-x86_64.pkg.tar.zst

You are done.

TIP

The package filename (qv2ray-dev-git-v1.99.4.2550-1-x86_64.pkg.tar.zst) depends on the actual version of Qv2ray. It may differ on your machine, but that's not a problem.

# openSUSE / Fedora / CentOS

Qv2ray is made available for openSUSE / Fedora / CentOS users from openSUSE Build Service (opens new window) by @zzndb (opens new window).

Applicable Versions

Because of the limit of Qt version, we may not be able to support all on-lifetime distro above, the detail of supported distro please check the OBS link below.

Similar to AUR, there are two versions of Qv2ray available. You can choose according to your own flavor:

Stable OBS: Qv2ray (opens new window)
Preview OBS: Qv2ray-preview (opens new window)

Or you can get more detailed installation guide directly from the links below:

Download Stable: Qv2ray (opens new window)
Download Preview: Qv2ray-preview (opens new window)

For CentOS user

Before you install Qv2ray from above OBS project, you need to add the EPEL repository which provided by Fedora for extra needed dependencies. For more info please check the Fedora EPEL Wiki (opens new window).

Plugins

The above OBS project (opens new window) also provide the plugins of Qv2ray family. After installing Qv2ray through project's repository (not download & install by hand), you can directly install plugins (with the same name of the plugin's project name, also provide the preview version plugin with -preview postfix) using your package manager.

# Homebrew (macOS/Linux)

You can use Homebrew to install Qv2ray on macOS (and Linux, maybe). If you haven't installed Homebrew yet, you can check the Homebrew website for more details about how to install it. Once Homebrew is installed, you can install Qv2ray using the following command:

$ brew cask install qv2ray

Or with the new command

$ brew install --cask qv2ray

Upgrading is also easy, just replace install with upgrade in the commands.

If you want to install plugins and Qv2ary beta, please add the malt tap:

brew tap kidonng/malt
brew install qv2ray-beta
# Or directly run
brew install kidonng/malt/qv2ray-beta

# Scoop (Windows)

Scoop (opens new window) is a command-line-based software packages manager for Windows.

Run the following commands in Powershell:

Install Scoop (opens new window):

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser # Allow script execution
iwr -useb get.scoop.sh | iex

Add extras bucket:
```
scoop bucket add extras
```
Install Qv2ray:
```
scoop install qv2ray
```
To update, just replace install with update in the commands:
```
scoop update qv2ray
```

(Optional) If you want to install plugins and Qv2ray beta, add sushi bucket:

scoop bucket add sushi https://github.com/kidonng/sushi
# For all apps see https://github.com/kidonng/sushi#qv2ray
scoop install qv2ray-beta

TIP

You may also need to install the latest Visual C++ Redistributable (opens new window).

# Chocolatey (Windows)

Chocolatey (opens new window) is another software packages manager for Windows。

Please open Powershell with administrator permission and run the following commands:

Install Chocolatey ：

Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://chocolatey.org/install.ps1'))

Install Qv2ray：
```
choco install qv2ray
```

# Download from an Linux app store

# Snapcraft

Follow the instructions on our Snapcraft page (opens new window).

# To install the package:
$ sudo snap install qv2ray
# sudo snap install qv2ray --edge (dev branch)
# To update the package:
$ sudo snap refresh qv2ray

# Flathub (Deprecated)

Deprecated (2020/09/18)

Installation of Qv2ray from Flathub is officially deprecated, since the maintainer is no longer actively maintaining the package. If you are interested in adopting this, please open an issue and let us know.

Set up Flatpak environment according to the official documentation (opens new window).

Install Qv2ray:

# To install the package:
$ flatpak install com.github.Qv2ray
# To update the package:
$ flatpak update

# Building From Source

Please refer to Manually Build Qv2ray Page.

⟵ Getting Started Configuring V2Ray Core ⟶

# Step 1: Getting Qv2ray Distribution

# GitHub Releases Binary

# GitHub Actions Artifact

# Download From a package manager

# Debian, Ubuntu and their derivatives

# Debian Stable install stable version of Qv2ray

# Debian Stable install the development version of Qv2ray

# Debian Unstable

# Ubuntu and its official derivatives install the stable version of Qv2ray

# Ubuntu and its official derivatives install the development version of Qv2ray

# Arch Linux-based distros

# Install directly from archlinuxcn

# Download from AUR, using an AUR Helper

# Download from AUR, the hard way

# openSUSE / Fedora / CentOS

# Homebrew (macOS/Linux)

# Scoop (Windows)

# Chocolatey (Windows)

# Download from an Linux app store

# Snapcraft

# Flathub (Deprecated)

# Building From Source

# Install directly from `archlinuxcn`