Skip to content

API Reference

Technical reference for the classes, methods, and functions exposed by the v2socks library.

The V2Socks Class

The primary class used to manage local SOCKS5 proxy client instances.

Constructor

V2Socks(config_link: str, port: int = None, verbose: bool = False)
  • config_link: String link of V2Ray config (VLESS/VMess/Trojan).
  • port: Optional TCP port to bind SOCKS5 client. If None or 0, a random free port is allocated.
  • verbose: Enables debug print output of Xray process startup logs.

Methods

  • start(): Validates configuration, downloads Xray core (if missing), and starts the background client process.
  • stop(): Shuts down the background process and deletes temporary JSON configs.
  • port() -> int: Returns the active local port proxy is running on.
  • is_alive() -> bool: Returns True if the background process is running successfully.
  • delay(target="https://www.google.com", timeout=5.0) -> float: Measures connection delay to the target URL in milliseconds (ms).
  • export_config() -> dict: Exports the generated configuration dictionary.

Properties

  • host: Returns "127.0.0.1".
  • socks_url: Returns the SOCKS5 proxy address string (e.g. "socks5://127.0.0.1:10808").

Class Methods

  • V2Socks.set_core_path(path: str): Configures a custom global path to a pre-installed Xray binary.
  • V2Socks.is_active(port: int) -> bool: Checks if there is an active client registered and running on port.

Core Management Functions

Helper functions to query and update the Xray core binary manually.

  • check_updates() -> dict: Queries the GitHub API to check for newer Xray releases. Returns a dictionary:
  • "has_update": bool
  • "latest_version": str
  • "local_version": str
  • update_core(version: str = None) -> str: Deletes the local binary and downloads the specified version (or the latest release if None).