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 msstoreThis 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 wingetEXE 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 onexrayseFor 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.debFor 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/OneXrayCoreRemove the application with:
sudo apt remove onexrayFedora RPM
Install or upgrade the downloaded RPM with DNF:
sudo dnf install ./OneXray-linux-x86_64.rpmFor 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/OneXrayCoreTo remove the application:
sudo dnf remove onexrayArch 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.zstTo 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/OneXrayCoreTo remove the application:
sudo pacman -R onexrayThe 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-binFedora
Use a Fedora version that meets the complete system-library baseline:
sudo dnf install unzip gtk3 glib2 libstdc++ libepoxy libX11 libXi procps-ng libcapArch Linux
On Arch Linux x86_64, update the system and install the dependencies together:
sudo pacman -Syu --needed unzip gtk3 libstdc++ procps-ng libcapExtract, 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
./OneXrayThe 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.