Skip to main content

python-v2ray

PyPI Version License: GPL v3 Python Versions Documentation

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:

📜 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)

Source distribution for python-v2ray 0.1.8
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)

Table of built distributions (wheels) for python-v2ray 0.1.8
File Interpreter ABI Platform Actions
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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page