Skip to content

Getting Started with v2socks

v2socks is a lightweight, generic, and cross-platform Python library that runs V2Ray configurations (VLESS, VMess, Trojan, Reality) as local SOCKS5 proxies.

It automatically handles the Xray core binary—downloading it on the first run to a shared, persistent directory (~/.v2socks/bin/)—and manages the local client process lifecycle.

Installation

Install the package via pip:

pip install v2socks

Quick Start

Start a proxy on an auto-allocated free port and fetch your new proxy IP:

import requests
from v2socks import V2Socks

# Use context manager to start and automatically close the client
with V2Socks("your-v2ray-config-link-here") as proxy:
    print(f"Proxy is running on local port: {proxy.port()}")

    # Configure requests proxies
    proxies = {"http": proxy.socks_url, "https": proxy.socks_url}

    # Perform HTTP request through proxy
    ip_info = requests.get("http://ip-api.com/json", proxies=proxies).json()
    print(f"Connected! Country: {ip_info.get('country')}")