Python bindings for Xray-core.
You have to install the following tools to be able to install this package successfully.
-
go in your PATH. go 1.20.0 and above is recommended. To check go is ready, type
go version
. Also, if google service is blocked in your region(such as Mainland China), you have to configure your GOPROXY to be able to pull go packages. For Chinese users, refer to goproxy.cn for more information. -
cmake in your PATH. To check cmake is ready, type
cmake --version
. -
A working GNU C++ compiler(i.e. GNU C++ toolchains). To check GNU C++ compiler is ready, type
g++ --version
. These tools should have been installed in Linux or macOS by default. If you don't have GNU C++ toolchains(especially for Windows users) anyway:
pip install Xray-core
>>> 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 string
This repository—including the package distributed on PyPI—contains source code from Xray-core, which has been modified to build Python bindings and expose a specific API. Unless otherwise noted, the version of this package aligns with the corresponding tag of the original source code, ensuring that the binding provides the same full feature set as the official Go distribution. Due to Xray-core's backward compatibility, there are no plans to generate bindings for older releases.
To simplify installation, the original Xray-core source code is not included as a submodule. To track the modifications made, you can compare the Python binding's source code against the corresponding version in the upstream Go repository.
Xray-core-python works on all major platform with all Python version(Python 3).
Below are tested build in github actions.
Platform | Python 3.8-Python 3.13 |
---|---|
ubuntu 22.04 | ✔️ |
ubuntu 24.04 | ✔️ |
windows-2019 | ✔️ |
windows-2022 | ✔️ |
windows-2025 | ✔️ |
macos-13 | ✔️ |
macos-14 | ✔️ |
macos-15 | ✔️ |
The license for this project follows its original go repository Xray-core and is under MPL 2.0.