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.

frompathlibimportPathfrompython_v2ray.downloaderimportBinaryDownloaderfrompython_v2ray.testerimportConnectionTesterfrompython_v2ray.config_parserimportparse_uridefrun_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()
exceptExceptionase:
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= [pforpin (parse_uri(uri) foruriintest_uris) ifp]
ifnotparsed_configs:
print("No valid configurations found to test.")
returnprint(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)
ifresults:
sorted_results=sorted(results, key=lambdax: x.get('ping_ms', 9999))
forresultinsorted_results:
tag=result.get('tag', 'N/A')
ping=result.get('ping_ms', -1)
status=result.get('status', 'error')
ifstatus=='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.