Xray-core-python
Python bindings for Xray-core.
Install
Core Building Tools
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:
Install Package
pip install Xray-core
API
>>> 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
Source Code Modification
This repository, including the package that distributes to pypi, contains Xray-core source code that's been modified to build the binding and specific API. If without explicitly remark, the version of this package corresponds to the version of the origin source code tag, so the binding will have full features as the original go distribution will have. And due to its backward compatibility, there's no plan to generate bindings for older release of Xray-core.
To make installation of this package easier, I didn't add the original Xray-core source code as a submodule. To track what modifications have been made to the source code, you can compare it with the same version under Python binding and corresponding go repository.
Tested Platform
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.14 |
|---|---|
| ubuntu 22.04 | :heavy_check_mark: |
| ubuntu 24.04 | :heavy_check_mark: |
| windows-2019 | :heavy_check_mark: |
| windows-2022 | :heavy_check_mark: |
| windows-2025 | :heavy_check_mark: |
| macos-13 | :heavy_check_mark: |
| macos-14 | :heavy_check_mark: |
| macos-15 | :heavy_check_mark: |
License
The license for this project follows its original go repository Xray-core and is under MPL 2.0.
1 maintainer
Release files for Xray-core 1.8.26.6
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| xray_core-1.8.26.6.tar.gz | 1.8 MB | Details |
Release files / xray_core-1.8.26.6.tar.gz
| Download URL | xray_core-1.8.26.6.tar.gz |
|---|---|
| Size | 1.8 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
fc4c60a1de905ebc6c9e558d398a0e665af5a39a6c5ee9b883ee9e904d7053d4
|
|
BLAKE2b-256 checksum How to use checksums |
c055f88658363045f955cac1ebc14d776c4f0fc325a7dced5034345410d0555a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 3, 2026.
Transparency log
