Python bindings for Xray-core.
Prebuilt binary wheels include the native Go and C++ binding, so a supported installation does not require Go, CMake, or a C++ compiler.
pip install Xray-core
Binary wheels are published for Linux x86-64 and ARM64, Windows x86-64 and ARM64, and macOS Intel and Apple Silicon.
A source distribution is also published as a fallback. If pip cannot find a compatible wheel, it may build the native binding from source. A source build requires:
- Go 1.26 or newer in
PATH. - A working C and C++ compiler toolchain.
- MinGW-w64 on Windows x86-64, or LLVM-MinGW on Windows ARM64, with
gccandg++available inPATH.
The isolated Python build environment installs CMake, pybind11, setuptools, and wheel automatically. To build directly from a repository checkout:
pip install .
>>> import xray
>>> help(xray) Help on package xray: NAME
xray
PACKAGE CONTENTS
xray
FUNCTIONS
queryStats(...) method of builtins.PyCapsule instance
queryStats(apiServer: str, timeout: int, myPattern: str, reset: bool) -> str
Query statistics from Xray
startFromJSON(...) method of builtins.PyCapsule instance
startFromJSON(json: str) -> None
Start Xray client with JSON stringThe source distribution vendors an exact Xray-core release so users can build the native binding without resolving a Git submodule. Binding-owned Go files are maintained separately from upstream-owned files, and a checked-in SHA-256 manifest makes unexpected changes fail validation.
UPSTREAM_VERSION, UPSTREAM_COMMIT, and the files under upstream/ record the exact source provenance.
The distributions are built and tested in GitHub Actions.
| Platform | Architecture | CPython |
|---|---|---|
| Linux | x86-64 | 3.8-3.14, 3.13t, 3.14t |
| Linux | ARM64 | 3.8-3.14, 3.13t, 3.14t |
| Windows | x86-64 | 3.8-3.14, 3.13t, 3.14t |
| Windows | ARM64 | 3.9-3.14, 3.13t, 3.14t |
| macOS | Intel | 3.8-3.14, 3.13t, 3.14t |
| macOS | Apple Silicon | 3.8-3.14, 3.13t, 3.14t |
The license for this project follows its original go repository Xray-core and is under MPL 2.0.