python-v2ray
A powerful, high-level Python wrapper for managing and testing V2Ray/Xray-core and Hysteria clients.
This library abstracts the complexities of binary management, multi-format config parsing, and concurrent connection testing, providing a clean and streamlined API for developers.
For full installation guides, core concepts, and the complete API reference, please visit our full documentation site.
✨ Features
- Automated Binary Management: Automatically downloads and manages the necessary
Xray-core,Hysteria, and test engine binaries for your platform (Windows, macOS, Linux). - Intelligent Subscription Handling: Effortlessly import configurations from subscription links. The loader intelligently handles both Base64 and plain-text formats and includes a powerful deduplication engine to clean up redundant profiles.
- Unified Config Parser: Seamlessly parses various link formats (
vless,vmess,trojan,ss,hysteria2,mvless) into a standardized Python object model. - High-Speed Concurrent Testing: Utilizes a hybrid architecture (Python + Go) to test dozens of configurations simultaneously, reporting latency, download, and upload speeds in seconds.
- Dynamic Config Builder: A fluent builder API to programmatically construct complex Xray JSON configurations with custom inbounds, outbounds, and routing rules.
- Advanced Proxy Chaining ("WARP on Any"): Easily route any configuration's traffic (VLESS, Trojan, even another WireGuard) through a final WARP outbound for enhanced privacy and connectivity.
- Live Statistics: Connect to a running Xray-core instance's gRPC API to fetch live traffic statistics (uplink & downlink).
- Cross-Platform: Designed to work flawlessly across Windows, macOS, and Linux environments.
🚀 Installation
Install the latest stable version from PyPI:
pip install python-v2ray
⚡️ Quick Start: Test a List of Proxies
This example demonstrates the core functionality: downloading dependencies, parsing URIs, and running a connection test. For more advanced examples, please see our full documentation.
from pathlib import Path
from python_v2ray.downloader import BinaryDownloader
from python_v2ray.tester import ConnectionTester
from python_v2ray.config_parser import parse_uri
def run_tests():
"""
An example of ensuring binaries, parsing URIs, and testing their connectivity.
"""
project_root = Path("./") # Assumes running from the project's root directory
# --- 1. Ensure all required binaries are available ---
print("--- Verifying binaries ---")
try:
downloader = BinaryDownloader(project_root)
downloader.ensure_all()
except Exception as e:
print(f"Fatal Error: {e}")
return
# --- 2. Define your list of proxy URIs ---
test_uris = [
"vless://...",
"vmess://...",
"hysteria2://...",
# ... add more of your configs here
]
# --- 3. Parse all URIs into a unified format ---
print("\n* Parsing URIs...")
parsed_configs = [p for p in (parse_uri(uri) for uri in test_uris) if p]
if not parsed_configs:
print("No valid configurations found to test.")
return
print(f"* Preparing to test {len(parsed_configs)} configurations concurrently...")
# --- 4. Initialize and run the tester ---
tester = ConnectionTester(
vendor_path=str(project_root / "vendor"),
core_engine_path=str(project_root / "core_engine")
)
results = tester.test_uris(parsed_configs)
# --- 5. Display the results, sorted by latency ---
print("\n" + "="*20 + " Test Results " + "="*20)
if results:
sorted_results = sorted(results, key=lambda x: x.get('ping_ms', 9999))
for result in sorted_results:
tag = result.get('tag', 'N/A')
ping = result.get('ping_ms', -1)
status = result.get('status', 'error')
if status == 'success':
print(f"✅ Tag: {tag:<35} | Latency: {ping:>4} ms | Status: {status}")
else:
print(f"❌ Tag: {tag:<35} | Latency: {ping:>4} ms | Status: {status.split('|').strip()}")
else:
print("No results were received from the tester.")
print("="*56)
if __name__ == "__main__":
run_tests()
🙏 Acknowledgments
This project would not be possible without the incredible work of the teams behind the core technologies it relies on. Special thanks to:
- GFW-knocker/Xray-core for the powerful and versatile Xray-core.
- apernet/hysteria for the feature-rich, high-performance Hysteria proxy.
📜 License
Distributed under the GNU General Public License v3.0. See LICENSE for more information.
Metadata
Release files for python-v2ray 0.1.8
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| python_v2ray-0.1.8.tar.gz | 36.5 kB | Without provenance | Details for python_v2ray-0.1.8.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| python_v2ray-0.1.8-py3-none-any.whl | Python 3 | none | any | Details for python_v2ray-0.1.8-py3-none-any.whl |
Total release size: 74.5 kB
Release files / python_v2ray-0.1.8.tar.gz
| Download URL | python_v2ray-0.1.8.tar.gz |
|---|---|
| Size | 36.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
f76647f3a7f991f178d092a2c21c96aed72cb5a8f3cae6208c483056d04dba6d
|
|
BLAKE2b-256 checksum How to use checksums |
92cb46d5d2995d8c98e8217543660a9e8cb691c0b0903340165d6a997cae48b1
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.11
|
Release files / python_v2ray-0.1.8-py3-none-any.whl
| Download URL | python_v2ray-0.1.8-py3-none-any.whl |
|---|---|
| Size | 38.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
fcccda13ec4205f226c0b224bb9170f3e8902738a233729e1a122ef3ff619207
|
|
BLAKE2b-256 checksum How to use checksums |
cfc67481065e14fd62acb1d4b61460d246e937269fa1c32866574fd8e1a52ff4
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.11
|
Security for python-v2ray 0.1.8
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.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.