Skip to content
Install OneXray

Download and install the OneXray Xray-core client

OneXray is an open-source Xray-core client for desktop and mobile. It does not include servers or a subscription: obtain a compatible configuration from your provider before connecting. You do not need to install a separate Xray-core command-line program.

After installation, add your servers or generate a configuration with AI. For connectivity problems, check the supported formats before changing platform settings.

Before downloading, check the system requirements, especially the Linux distribution and runtime-library baseline.

Choose your platform

Platform Requirements Downloads
iPhone / iPad iOS / iPadOS 16+ App Store · IPA
Mac App Store macOS 13+, Apple silicon or Intel App Store
Mac — OneXraySE macOS 13+, Apple silicon or Intel Homebrew · Universal ZIP
Android phones / tablets Android 10+ (API 29), arm64-v8a or x86_64 Google Play · APK
Windows x64 Windows 10 20H2 (19042)+ Microsoft Store · EXE (winget) · ZIP
Windows ARM64 Windows 11 Microsoft Store · EXE (winget) · ZIP
Linux x86_64 glibc 2.39+, GLib 2.80+, GTK 3, kernel 5.3+ DEB · RPM · pacman · ZIP
Linux arm64 glibc 2.39+, GLib 2.80+, GTK 3, kernel 5.3+ DEB · RPM · pacman · ZIP

See release notes and available assets. Android 32-bit ARM is not supported.

Windows

Microsoft Store

Install from Microsoft Store or use winget with the store source:

winget install --id 9NJ0MVHW215D --source msstore

This edition uses MSIX and Windows system VPN without UAC for Core. Microsoft Store handles architecture selection and updates.

Standalone EXE / ZIP

Install the standalone EXE through the winget community source:

winget install --id YuanDevLLC.OneXray -e --source winget

EXE and ZIP use a native TUN. Starting VPN requests administrator approval for Core, not for the main app. Extract the entire ZIP before opening OneXray; it does not register links or create shortcuts automatically.

EXE/ZIP and MSIX have separate data locations; switching channels is not an in-place data migration. Both require an explicit Xray outbound-interface selection. Windows behavior.

All Windows packages include the matching Microsoft Visual C++ runtime. The GUI does not require a separate runtime installation.

macOS

Mac App Store uses a Packet Tunnel extension. OneXraySE uses a System Extension:

brew install --cask onexrayse

For ZIP, move OneXraySE.app to /Applications before opening it. Complete Setup, enter the main interface, and approve the VPN/Network Extension requests. macOS may direct you to Login Items & Extensions or Privacy & Security; follow any restart prompt. To update the ZIP edition, quit the app, replace it in /Applications, and approve extension updates if requested.

See Apple’s System Extension installation guide.

iOS IPA

The App Store is the simplest option. Sideloading an IPA requires re-signing both the app and its Packet Tunnel extension with profiles that permit Network Extension. A free Personal Team does not provide that capability. See Apple’s supported capabilities.

Linux

Check the Linux system requirements first: DEB, RPM, pacman and ZIP packages share the glibc 2.39+, GLib 2.80+, GTK 3 and kernel 5.3+ baseline. Ubuntu 22.04 is not compatible.

Choose the package for your distribution and CPU from the files provided by the selected release. If that release does not include your distribution’s native package, use ZIP.

Before installing, upgrading or removing a package, stop the VPN and quit OneXray. DEB, RPM and pacman install their declared dependencies and grant Core its network capabilities during installation and upgrades; you do not normally need to run setcap yourself. Open the graphical app as your normal desktop user, not with sudo. The getcap checks below should include cap_net_admin,cap_net_raw=eip.

Debian / Ubuntu DEB

On a compatible Debian/Ubuntu system, install the downloaded package:

sudo apt install ./OneXray-linux-x86_64.deb

For arm64, use OneXray-linux-aarch64.deb. To upgrade, download the newer DEB and run the same command with its path. Open OneXray from your application menu, or run OneXray in a terminal, preserving the capital letters.

Core is installed at /opt/OneXray/OneXrayCore. To inspect its capabilities:

getcap /opt/OneXray/OneXrayCore

Remove the application with:

sudo apt remove onexray

Fedora RPM

Install or upgrade the downloaded RPM with DNF:

sudo dnf install ./OneXray-linux-x86_64.rpm

For arm64, use OneXray-linux-aarch64.rpm. Open OneXray from your application menu, or run onexray in a terminal. Core is installed at /usr/share/onexray/OneXrayCore:

getcap /usr/share/onexray/OneXrayCore

To remove the application:

sudo dnf remove onexray

Arch Linux pacman

On Arch Linux x86_64, update the system first, then install the downloaded package:

sudo pacman -Syu
sudo pacman -U ./OneXray-linux-x86_64.pkg.tar.zst

To upgrade OneXray, download the newer package and repeat the commands with its path. The OneXray-linux-aarch64.pkg.tar.zst artifact is for compatible ARM64 distributions; standard Arch Linux uses x86_64. Open OneXray from your application menu, or run OneXray in a terminal, preserving the capital letters.

Core is installed at /opt/OneXray/OneXrayCore:

getcap /opt/OneXray/OneXrayCore

To remove the application:

sudo pacman -R onexray

The removal commands above remove the installed package and leave OneXray’s per-user data in place. Installing a downloaded package does not add a OneXray package repository: repeat the local-file installation command for later releases. Continue with first connection after opening the app.

ZIP for Ubuntu, Fedora and Arch Linux

ZIP requires you to install the runtime dependencies and grant Core its network capabilities manually. Choose the commands for your distribution below, then follow the shared extraction and launch steps. These commands do not change the minimum library versions in the system requirements.

Ubuntu 24.04 LTS

sudo apt install -y unzip libgtk-3-0t64 libglib2.0-0t64 libstdc++6 libepoxy0 libx11-6 libxi6 procps libcap2-bin

Fedora

Use a Fedora version that meets the complete system-library baseline:

sudo dnf install unzip gtk3 glib2 libstdc++ libepoxy libX11 libXi procps-ng libcap

Arch Linux

On Arch Linux x86_64, update the system and install the dependencies together:

sudo pacman -Syu --needed unzip gtk3 libstdc++ procps-ng libcap

Extract, authorize Core and launch

Download the ZIP matching your CPU architecture from the table above. The example below uses x86_64 and saves the entire bundle under $HOME/Applications/OneXray; for arm64, replace the archive name with OneXray-linux-aarch64.zip. Adjust the download path if your browser saved it elsewhere.

mkdir -p "$HOME/Applications/OneXray"
unzip "$HOME/Downloads/OneXray-linux-x86_64.zip" -d "$HOME/Applications/OneXray"
cd "$HOME/Applications/OneXray"
chmod +x ./OneXray ./OneXrayCore
sudo setcap cap_net_admin,cap_net_raw+eip ./OneXrayCore
getcap ./OneXrayCore
./OneXray

The ZIP contains the executables directly; the extraction command creates their enclosing directory. OneXrayCore is beside the OneXray executable in $HOME/Applications/OneXray. Keep lib/, data/ and the other bundled files in that directory. Run the graphical app as your normal desktop user; sudo above is only for dependency installation and granting Core capabilities.

To update, stop the VPN and quit OneXray, replace the complete extracted bundle, then repeat chmod and setcap on the new files before launching. File capabilities do not carry over when Core is replaced. ZIP does not register onexray:// links. GNOME may need the AppIndicator extension for tray controls.

Core process monitoring requires Linux kernel 5.3 or newer with pidfd support. On Linux ARM64, Chinese/Japanese/Korean language selections currently display English without changing the saved preference; see language settings.

Continue with first connection.

Last updated on