v2socks 1.0.0

A generic Python library to run V2Ray configurations as local SOCKS5 proxies.

v2socks

Convert V2Ray/Xray configurations (VLESS, VMess, Trojan, Reality) to local SOCKS5 proxies in Python.

📚 English Documentation | 📚 مستندات فارسی

---

Installation

Install the package via pip:

pip install v2socks

---

Quick Start

Run a local SOCKS5 proxy from a V2Ray config link and fetch your new IP location:

import requests
from v2socks import V2Socks

# Start proxy on an auto-allocated free port (Xray core downloads automatically on first run)
with V2Socks("your-v2ray-config-link-here") as proxy:
    print(f"Proxy is running on local port: {proxy.port()}")
    
    # Use with requests
    proxies = {"http": proxy.socks_url, "https": proxy.socks_url}
    ip_info = requests.get("http://ip-api.com/json", proxies=proxies).json()
    print(f"Connected! Country: {ip_info.get('country')}")

---

Features

• Zero Configuration: Automatically detects your platform (Windows, Linux, macOS) and downloads the stable Xray core on the first run.
• Framework Agnostic: Fully decoupled from any bot or client libraries. Exposes a standard SOCKS5 URL.
• xHTTP Protocol Support: Supports the latest V2Ray/Xray protocols including VLESS, VMess, Trojan, Reality, WebSocket, gRPC, and xHTTP.
• Multiple Clients: Run multiple client proxies simultaneously on different free ports.
• Delay Testing: Built-in latency testing using a raw TCP SOCKS5 handshake (in milliseconds).
• Context Manager: Pythonic with blocks ensure background processes are stopped and cleaned up cleanly on exit.

---

Examples

Running Multiple Proxies Simultaneously

from v2socks import V2Socks

config_1 = "vless://..."
config_2 = "vmess://..."

# Start first proxy on automatic port, and second on custom port 10808
with V2Socks(config_1) as proxy1, V2Socks(config_2, port=10808) as proxy2:
    print(f"Proxy 1: socks5://127.0.0.1:{proxy1.port()}")
    print(f"Proxy 2: socks5://127.0.0.1:{proxy2.port()}")

Custom Xray Path

Use your own pre-installed Xray executable globally instead of the auto-downloaded one:

from v2socks import V2Socks

V2Socks.set_core_path("/usr/bin/xray")

---

API Reference

V2Socks(config_link, port=None, verbose=False)

• start(): Starts the background Xray client.
• stop(): Terminates the client and cleans up config files.
• port() -> int: Returns the active local SOCKS5 proxy port.
• is_alive() -> bool: Returns True if the client process is running.
• delay(target="https://www.google.com", timeout=5.0) -> float: Measures connection delay to the target URL in milliseconds.
• export_config() -> dict: Exports the generated Xray JSON configuration.
• host (Property): Returns "127.0.0.1".
• socks_url (Property): Returns "socks5://127.0.0.1:port".

Class Methods

• V2Socks.set_core_path(path: str): Set custom path to Xray core globally.
• V2Socks.is_active(port: int) -> bool: Check if there is an active client running on port.

Module Functions

• check_updates() -> dict: Check for updates on GitHub. Returns a dictionary containing has_update, latest_version, and local_version.
• update_core(version=None): Update local Xray core to the latest or a specific release version.

---

Exceptions

All exceptions inherit from the base class V2SocksError:

• ParseError: Config link parsing failed or protocol is unsupported.
• CoreNotFoundError: Xray executable is missing or not executable.
• DownloadError: Xray download or extraction failed.
• ConnectionError: Connection to target or delay check failed.

---

FAQ

Where is the Xray binary downloaded?

The binary is downloaded to ~/.v2socks/bin/ so it is shared across all Python projects and is not deleted when reinstalling the package.

Does it support Windows and macOS?

Yes, v2socks is fully cross-platform and supports Windows, Linux, and macOS (Intel & Apple Silicon).

---

License

MIT