# v2ray2proxy
A Python library to convert V2Ray configuration links (vmess://, vless://, ss://, trojan://) to usable HTTP and SOCKS5 proxies for Python HTTP clients.
## Features
- Convert V2Ray links to local proxy instances
- **Automatic V2Ray core download** - no external installation needed
- Support for all major V2Ray protocols:
- VMess
- VLESS
- Shadowsocks
- Trojan
- Proxy pool for load balancing and failover
- Works with both synchronous and asynchronous HTTP clients
- Clean, Pythonic API
## Installation
```bash
pip install v2ray2proxy
```
## Usage
### Basic Usage
```python
from v2ray2proxy import V2RayProxy
import requests
# Create a proxy from a V2Ray link
proxy = V2RayProxy("vmess://...")
try:
# Use with requests
proxies = {
"http": proxy.http_proxy_url,
"https": proxy.http_proxy_url
}
response = requests.get("https://api.ipify.org?format=json", proxies=proxies)
print(response.json())
finally:
# Always stop the proxy when done
proxy.stop()
```
### Using with aiohttp (Async)
```python
import asyncio
import aiohttp
from v2ray2proxy import V2RayProxy
async def main():
# Create a proxy from a V2Ray link
proxy = V2RayProxy("vmess://...")
try:
# Use with aiohttp
async with aiohttp.ClientSession() as session:
async with session.get(
"https://api.ipify.org?format=json",
proxy=proxy.http_proxy_url
) as response:
data = await response.json()
print(data)
finally:
# Always stop the proxy when done
proxy.stop()
asyncio.run(main())
```
### Proxy Pool for Load Balancing
```python
from v2ray2proxy import V2RayPool
import requests
# Create a pool with multiple proxies
links = [
"vmess://...",
"vless://...",
"trojan://..."
]
pool = V2RayPool(v2ray_links=links)
try:
# Get the fastest proxy from the pool
proxy = pool.get_fastest_proxy()
# Use the proxy
proxies = {
"http": proxy.http_proxy_url,
"https": proxy.http_proxy_url
}
response = requests.get("https://api.ipify.org?format=json", proxies=proxies)
print(response.json())
# You can also get a proxy using different strategies
# Round-robin
proxy = pool.get_proxy(strategy="round-robin")
# Random
proxy = pool.get_proxy(strategy="random")
# Get proxy URLs directly from the pool
http_url = pool.http_proxy_url()
socks5_url = pool.socks5_proxy_url()
finally:
# Always stop the pool when done
pool.stop()
```
### Command Line Usage
```bash
# Start a proxy and print the details
python -m v2ray2proxy "vmess://..."
# Test the proxy after starting
python -m v2ray2proxy "vmess://..." --test
# Specify custom ports
python -m v2ray2proxy "vmess://..." --http-port 8080 --socks-port 1080
# Start a proxy pool with multiple instances of the same link
python -m v2ray2proxy "vmess://..." --pool --pool-size 3
```
## Supported Link Types
- **VMess**: `vmess://...` - V2Ray's VMess protocol
- **VLESS**: `vless://...` - V2Ray's VLESS protocol
- **Shadowsocks**: `ss://...` - Shadowsocks protocol
- **Trojan**: `trojan://...` - Trojan protocol
## Requirements
- Python 3.9+
- No external V2Ray installation needed (automatically downloaded)
## Advanced Usage
### Custom Ports
```python
from v2ray2proxy import V2RayProxy
# Specify custom ports
proxy = V2RayProxy(
"vmess://...",
http_port=8080,
socks_port=1080
)
```
### Checking Proxy Health
```python
from v2ray2proxy import V2RayPool
pool = V2RayPool(v2ray_links=["vmess://...", "vmess://..."])
# Check health of all proxies
health_status = pool.check_health()
print(health_status)
# Automatically restart unhealthy proxies
pool.auto_failover()
```
### Configuration Only Mode
If you only want to generate the configuration without starting the proxy:
```python
from v2ray2proxy import V2RayProxy
import json
proxy = V2RayProxy("vmess://...", config_only=True)
# Get the V2Ray configuration
config = proxy.generate_config()
print(json.dumps(config, indent=2))
# Create the config file
config_path = proxy.create_config_file()
print(f"Config file created at: {config_path}")
```
## Some thoughts
Each v2ray instance eats about ~17MB of RAM on Linux, under 10MB on W11
## License
MIT
Raw data
{
"_id": null,
"home_page": null,
"name": "v2ray2proxy",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "v2ray, v2core, v2ray-core, proxy, vless, vmess, shadowsocks, trojan, python, cli",
"author": null,
"author_email": "nichind <nichinddev@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/0f/fe/bfa7e3adafb260b1df97c6182d53ea05e2a20064572d2c8294137e6b5a35/v2ray2proxy-0.2.7.tar.gz",
"platform": null,
"description": "# v2ray2proxy\n\nA Python library to convert V2Ray configuration links (vmess://, vless://, ss://, trojan://) to usable HTTP and SOCKS5 proxies for Python HTTP clients.\n\n## Features\n\n- Convert V2Ray links to local proxy instances\n- **Automatic V2Ray core download** - no external installation needed\n- Support for all major V2Ray protocols:\n - VMess\n - VLESS\n - Shadowsocks\n - Trojan\n- Proxy pool for load balancing and failover\n- Works with both synchronous and asynchronous HTTP clients\n- Clean, Pythonic API\n\n## Installation\n\n```bash\npip install v2ray2proxy\n```\n\n## Usage\n\n### Basic Usage\n\n```python\nfrom v2ray2proxy import V2RayProxy\nimport requests\n\n# Create a proxy from a V2Ray link\nproxy = V2RayProxy(\"vmess://...\")\n\ntry:\n # Use with requests\n proxies = {\n \"http\": proxy.http_proxy_url,\n \"https\": proxy.http_proxy_url\n }\n \n response = requests.get(\"https://api.ipify.org?format=json\", proxies=proxies)\n print(response.json())\nfinally:\n # Always stop the proxy when done\n proxy.stop()\n```\n\n### Using with aiohttp (Async)\n\n```python\nimport asyncio\nimport aiohttp\nfrom v2ray2proxy import V2RayProxy\n\nasync def main():\n # Create a proxy from a V2Ray link\n proxy = V2RayProxy(\"vmess://...\")\n \n try:\n # Use with aiohttp\n async with aiohttp.ClientSession() as session:\n async with session.get(\n \"https://api.ipify.org?format=json\",\n proxy=proxy.http_proxy_url\n ) as response:\n data = await response.json()\n print(data)\n finally:\n # Always stop the proxy when done\n proxy.stop()\n\nasyncio.run(main())\n```\n\n### Proxy Pool for Load Balancing\n\n```python\nfrom v2ray2proxy import V2RayPool\nimport requests\n\n# Create a pool with multiple proxies\nlinks = [\n \"vmess://...\",\n \"vless://...\",\n \"trojan://...\"\n]\n\npool = V2RayPool(v2ray_links=links)\n\ntry:\n # Get the fastest proxy from the pool\n proxy = pool.get_fastest_proxy()\n \n # Use the proxy\n proxies = {\n \"http\": proxy.http_proxy_url,\n \"https\": proxy.http_proxy_url\n }\n \n response = requests.get(\"https://api.ipify.org?format=json\", proxies=proxies)\n print(response.json())\n \n # You can also get a proxy using different strategies\n # Round-robin\n proxy = pool.get_proxy(strategy=\"round-robin\")\n # Random\n proxy = pool.get_proxy(strategy=\"random\")\n \n # Get proxy URLs directly from the pool\n http_url = pool.http_proxy_url()\n socks5_url = pool.socks5_proxy_url()\nfinally:\n # Always stop the pool when done\n pool.stop()\n```\n\n### Command Line Usage\n\n```bash\n# Start a proxy and print the details\npython -m v2ray2proxy \"vmess://...\"\n\n# Test the proxy after starting\npython -m v2ray2proxy \"vmess://...\" --test\n\n# Specify custom ports\npython -m v2ray2proxy \"vmess://...\" --http-port 8080 --socks-port 1080\n\n# Start a proxy pool with multiple instances of the same link\npython -m v2ray2proxy \"vmess://...\" --pool --pool-size 3\n```\n\n## Supported Link Types\n\n- **VMess**: `vmess://...` - V2Ray's VMess protocol\n- **VLESS**: `vless://...` - V2Ray's VLESS protocol\n- **Shadowsocks**: `ss://...` - Shadowsocks protocol\n- **Trojan**: `trojan://...` - Trojan protocol\n\n## Requirements\n\n- Python 3.9+\n- No external V2Ray installation needed (automatically downloaded)\n\n## Advanced Usage\n\n### Custom Ports\n\n```python\nfrom v2ray2proxy import V2RayProxy\n\n# Specify custom ports\nproxy = V2RayProxy(\n \"vmess://...\",\n http_port=8080,\n socks_port=1080\n)\n```\n\n### Checking Proxy Health\n\n```python\nfrom v2ray2proxy import V2RayPool\n\npool = V2RayPool(v2ray_links=[\"vmess://...\", \"vmess://...\"])\n\n# Check health of all proxies\nhealth_status = pool.check_health()\nprint(health_status)\n\n# Automatically restart unhealthy proxies\npool.auto_failover()\n```\n\n### Configuration Only Mode\n\nIf you only want to generate the configuration without starting the proxy:\n\n```python\nfrom v2ray2proxy import V2RayProxy\nimport json\n\nproxy = V2RayProxy(\"vmess://...\", config_only=True)\n\n# Get the V2Ray configuration\nconfig = proxy.generate_config()\nprint(json.dumps(config, indent=2))\n\n# Create the config file\nconfig_path = proxy.create_config_file()\nprint(f\"Config file created at: {config_path}\")\n```\n\n## Some thoughts\n\nEach v2ray instance eats about ~17MB of RAM on Linux, under 10MB on W11\n\n## License\n\nMIT\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "\ud83d\udc0d Convert v2ray (vless://, vmess://, ss:// , trojan://) to local socks5:// & http:// proxies",
"version": "0.2.7",
"project_urls": {
"Homepage": "https://github.com/nichind/v2ray2proxy",
"Issues": "https://github.com/nichind/v2ray2proxy/issues"
},
"split_keywords": [
"v2ray",
" v2core",
" v2ray-core",
" proxy",
" vless",
" vmess",
" shadowsocks",
" trojan",
" python",
" cli"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "d93e24ec3b9e9ac217d799090a75b2bde6236d12944277edcfc6732e4a75c4a8",
"md5": "49dc8759bcee6f0a187288f451a9b7e8",
"sha256": "36c835de146f186c02eaa0035e3cd49ebab8304a0f6c758ec2bb6e92eb35934e"
},
"downloads": -1,
"filename": "v2ray2proxy-0.2.7-py3-none-any.whl",
"has_sig": false,
"md5_digest": "49dc8759bcee6f0a187288f451a9b7e8",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 30062,
"upload_time": "2025-08-16T20:14:41",
"upload_time_iso_8601": "2025-08-16T20:14:41.541288Z",
"url": "https://files.pythonhosted.org/packages/d9/3e/24ec3b9e9ac217d799090a75b2bde6236d12944277edcfc6732e4a75c4a8/v2ray2proxy-0.2.7-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "0ffebfa7e3adafb260b1df97c6182d53ea05e2a20064572d2c8294137e6b5a35",
"md5": "e3b1ccb6ed7ee0d910e55f6873c5bd11",
"sha256": "72f5d33ae7da11d2d523cb3fa4928eefa03a020662ae9b87f73c4bd3625417b4"
},
"downloads": -1,
"filename": "v2ray2proxy-0.2.7.tar.gz",
"has_sig": false,
"md5_digest": "e3b1ccb6ed7ee0d910e55f6873c5bd11",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 26682,
"upload_time": "2025-08-16T20:14:42",
"upload_time_iso_8601": "2025-08-16T20:14:42.883592Z",
"url": "https://files.pythonhosted.org/packages/0f/fe/bfa7e3adafb260b1df97c6182d53ea05e2a20064572d2c8294137e6b5a35/v2ray2proxy-0.2.7.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-16 20:14:42",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "nichind",
"github_project": "v2ray2proxy",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "psutil",
"specs": []
}
],
"lcname": "v2ray2proxy"
}
JSON
