Overview

V2Kit is a lightweight and extensible Python toolkit for working with V2Ray proxy configurations and subscriptions. It provides a clean API for common operations such as protocol detection, configuration validation, config relabeling, and subscription encoding/decoding. The project is designed with simplicity, predictability, and composability in mind, making it suitable for automation scripts, proxy pipelines, networking tools, and future extensions around V2Ray ecosystem utilities.

PyPI Counter
Github Stars

Branch	main	dev
CI

Code Quality

Installation

Source Code

• Download Version 0.6 or Latest Source
• pip install .

PyPI

• Check Python Packaging User Guide
• pip install v2kit==0.6

Supported Protocols

V2Kit currently supports the following protocols:

Protocol	Detection	Parsing	Relabeling	Config Model
VMESS	✅	✅	✅	✅
VLESS	✅	✅	✅	✅
Trojan	✅	✅	✅	✅
Shadowsocks	✅	✅	✅	✅
SOCKS	✅	✅	✅	✅
HTTP	✅	✅	✅	✅

Usage

URI Utilities

from v2kit import (
    decode_subscription,
    encode_subscription,
    is_vmess,
    parse,
    relabel,
)

uri = "vmess://eyJhZGQiOiIxMjcuMC4wLjEiLCJwcyI6Im9sZCJ9"

new_uri = relabel(uri, "Germany-1")

if is_vmess(new_uri):
    print("VMESS URI detected")

config = parse(new_uri)

config.update_label("Germany-2")

subscription = encode_subscription([config])

uris = decode_subscription(subscription)

Configs

from v2kit import VMESSConfig

config = VMESSConfig(
    uuid="550e8400-e29b-41d4-a716-446655440000",
    address="example.com",
    port=443,
    label="Germany-1",
)

uri = config.to_uri()

Issues & Bug Reports

Just fill an issue and describe it. We'll check it ASAP!

• Please complete the issue template

Show Your Support

Star This Repo

Give a ⭐️ if this project helped you!

Donate to Our Project

Bitcoin

1KtNLEEeUbTEK9PdN6Ya3ZAKXaqoKUuxCy

Ethereum

0xcD4Db18B6664A9662123D4307B074aE968535388

Litecoin

Ldnz5gMcEeV8BAdsyf8FstWDC6uyYR6pgZ

Doge

DDUnKpFQbBqLpFVZ9DfuVysBdr249HxVDh

Tron

TCZxzPZLcJHr2qR3uPUB1tXB6L3FDSSAx7

Ripple

rN7ZuRG7HDGHR5nof8nu5LrsbmSB61V1qq

Binance Coin

bnb1zglwcf0ac3d0s2f6ck5kgwvcru4tlctt4p5qef

Tether

0xcD4Db18B6664A9662123D4307B074aE968535388

Dash

Xd3Yn2qZJ7VE8nbKw2fS98aLxR5M6WUU3s

Stellar

GALPOLPISRHIYHLQER2TLJRGUSZH52RYDK6C3HIU4PSMNAV65Q36EGNL

Zilliqa

zil1knmz8zj88cf0exr2ry7nav9elehxfcgqu3c5e5

Coffeete

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog and this project adheres to Semantic Versioning.

Unreleased

0.6 - 2026-09-01

Added

• clear_extra method
• set_extra_item method
• get_extra_item method
• remove_extra_item method

Changed

• _get_protocol function modified
• decode_subscription function blank line bug fixed
• Port validation bug fixed
• AlterId validation bug fixed
• Test system modified
• Parsers updated

0.5 - 2026-07-31

Added

• encoded_label property
• uri_label property

Changed

• encode_subscription function modified
• parse function modified
• extra property modified
• update_extra method modified
• to_uri method modified
• to_dict method modified
• Protocol enum updated
• Scheme bug fixed
• VMESS parser bug fixed
• Test system modified

0.4 - 2026-07-02

Added

• HttpConfig class

Changed

• parse function modified
• README.md updated
• Test system modified

0.3 - 2026-06-16

Added

• Logo
• SocksConfig class
• is_socks function

Changed

• README.md updated
• Test system modified
• Dependencies structure modified
• All config models moved to models folder

0.2 - 2026-06-04

Added

• VMESSConfig class
• VLESSConfig class
• TrojanConfig class
• ShadowsocksConfig class
• V2kitError class
• V2kitValidationError class
• V2kitParseError class
• parse function

Changed

• README.md updated
• Test system modified
• is_vmess function config parameter renamed to uri
• is_vless function config parameter renamed to uri
• is_trojan function config parameter renamed to uri
• is_shadowsocks function config parameter renamed to uri
• encode_subscription function configs parameter renamed to entries

0.1 - 2026-05-16

Added

• is_vmess function
• is_vless function
• is_trojan function
• is_shadowsocks function
• relabel function
• encode_subscription function
• decode_subscription function