Installation

Requirements

  • Python 3.10 or newer

  • Windows or Linux on a supported architecture

  • HTTPS access to GitHub for automatic first-use core installation

Install from PyPI:

python -m pip install --upgrade v2root

Verify:

import v2root

print(v2root.__version__)

Automatic Core Installation

The wheel does not contain a native binary. The first V2RootClient() construction installs the latest official compatible V2Root Core when needed:

from v2root import V2RootClient

client = V2RootClient()
print(client.library_path)

Default cache locations:

  • Windows: %LOCALAPPDATA%\\V2Root\\core

  • Linux: $XDG_CACHE_HOME/v2root/core or ~/.cache/v2root/core

Set V2ROOT_CORE_HOME to override the core cache.

Offline and Pinned Installation

Install a known release before creating the client:

from v2root import CoreManager, V2RootClient

manager = CoreManager()
manager.install("v2root-v26.3.27")
client = V2RootClient(core_manager=manager, auto_install=False)

Load a development build directly:

client = V2RootClient(core_path="/opt/v2root/xray-linux-amd64.so")

The explicit binary must match the operating system, architecture, and V2Root 2.0 ABI.

Application Dependencies

V2Root depends only on colorama. Native V2Root Core is managed separately from Python package dependencies.