## singbox2proxy
[](https://pypi.org/project/singbox2proxy/)[](https://github.com/nichind/singbox2proxy/actions/workflows/build.yml) [](https://github.com/nichind/singbox2proxy/actions/workflows/publish.yml)
Integrate sing-box proxies into your python applications with ease on any device.
- sing-box auto-install & easy management
- zero dependencies for base functionality
- seamless integration with existing applications
- tuned for best performance and latency in mind
### Supported Protocols
This module supports these sing-box protocols:
- VMess (`vmess://`)
- VLESS (`vless://`)
- Shadowsocks (`ss://`)
- Trojan (`trojan://`)
- Hysteria2* (`hy2://`, `hysteria2://`)
- Hysteria* (`hysteria://`)
- TUIC* (`tuic://`)
- WireGuard (`wg://`)
- SSH (`ssh://`)
- HTTP/HTTPS (`http://`, `https://`)
- SOCKS (`socks://`, `socks4://`, `socks5://`)
- NaiveProxy* (`naive+https://`)
*: Chaining as a middle proxy not supported, according to the [sing-box docs](https://sing-box.sagernet.org/configuration/inbound/)
### Installation
with pip
```shell
pip install singbox2proxy
```
with [uv](https://pypi.org/project/uv/)
```shell
uv pip install singbox2proxy
```
build from source
```shell
git clone https://github.com/nichind/singbox2proxy.git
cd singbox2proxy
pip install -e .
```
### Python Usage
Using built-in client powered by [curl-cffi](https://pypi.org/project/curl-cffi/) or [requests](https://pypi.org/project/requests/)
```python
from singbox2proxy import SingBoxProxy
proxy = SingBoxProxy("vless://...")
response = proxy.request("GET", "https://api.ipify.org?format=json") # IF curl-cffi is installed, it will be used; otherwise, requests will be used.
print(response.status_code, response.text) # 200, {"ip":"..."}
```
Integrating with your own HTTP client
```python
import requests
from singbox2proxy import SingBoxProxy
proxy = SingBoxProxy("hy2://...")
session = requests.Session()
session.proxies = proxy.proxy_for_requests # {"http": "http://127.0.0.1:<port>", "https": "http://127.0.0.1:<port>"}
response = session.get("https://api.ipify.org?format=json")
print(response.status_code, response.text) # 200, {"ip":"..."}
```
Example with aiohttp
```python
from singbox2proxy import SingBoxProxy
import aiohttp
async def main():
proxy = SingBoxProxy("vmess://...")
async with aiohttp.ClientSession(proxy=proxy.socks5_proxy_url or proxy.http_proxy_url) as session:
async with session.get("https://api.ipify.org?format=json") as response:
print(response.status, await response.text()) # 200, {"ip":"..."}
```
#### Chaining
Chained proxies allow you to route your traffic through multiple proxy servers if you'll ever need more privacy or easy restriction bypass. You can chain multiple proxies together by specifying a `chain_proxy` with a gate `SingBoxProxy` instance when creating a new `SingBoxProxy`.
> [!NOTE]
> See what protocols can be used as middleman proxies at [supported protocols](#supported-protocols)
```python
from singbox2proxy import SingBoxProxy
proxy1 = SingBoxProxy("vmess://...")
proxy2 = SingBoxProxy("vless://...", chain_proxy=proxy1)
response = proxy2.request("GET", "https://api.ipify.org?format=json")
print(response.status_code, response.text) # 200, {"ip": "<proxy2's IP>"}
# Here, requests made through `proxy2` will first go through `proxy1`, then proxy1 will forward the request to proxy2, and finally proxy2 will send the request to the target server.
```
#### TUN Mode (System-Wide VPN)
Create a virtual network interface to route all system traffic through the proxy. This requires root/administrator privileges.
> [!IMPORTANT]
> Very experimental, use at your own risk.
```python
# Requires root/admin privileges
proxy = SingBoxProxy("vless://...", tun_enabled=True)
# All system traffic is now routed through the proxy
# Use like a normal VPN connection
```
#### System Proxy Configuration
Automatically configure your OS proxy settings. This is a great alternative to TUN mode when you don't have root access.
> [!NOTE]
> The system proxy settings will be restored to their original state when the `SingBoxProxy` instance is closed or goes out of scope, but multiple instances may interfere with each other, may be better to backup your initial settings before using this feature.
```python
# Automatically sets system proxy and restores on exit
with SingBoxProxy("vless://...", set_system_proxy=True) as proxy:
# Your web browser and other apps will now use the proxy
print(f"System proxy configured to use {proxy.http_proxy_url}")
```
### CLI
> [!NOTE]
> If the `singbox2proxy` or `sb2p` command isn't working in your terminal, use `python -m singbox2proxy <command>`, `uv run -m singbox2proxy <command>`, etc. instead.
#### Basic Commands
Start a single proxy:
```shell
sb2p "vmess://eyJ2IjoiMiIsInBzIj..."
```
Specify custom ports:
```shell
sb2p "ss://..." --http-port 8080 --socks-port False # Socks disabled
```
Test the proxy connection:
```shell
sb2p "trojan://..." --test
```
#### Proxy Chaining
Chain multiple proxies (traffic flows: you -> proxy1 -> proxy2 -> target):
```shell
sb2p "vmess://..." "vless://..." "hy2://..." --chain
```
> [!NOTE]
> See what protocols can be used as middleman proxies at [supported protocols](#supported-protocols)
The first URL becomes the entry point, and the last URL connects to the target server.
#### Configuration Management
Generate configuration without starting:
```shell
sb2p "vless://..." --config-only
```
Save configuration to file:
```shell
sb2p "vmess://..." --output-config config.json
```
#### Logging Options
Enable verbose logging:
```shell
sb2p "ss://..." --verbose
```
Disable all logging:
```shell
sb2p "hy2://..." --quiet
```
#### TUN Mode (System-Wide VPN)
Enable TUN mode to route all system traffic through the proxy.
```shell
# Linux/macOS (requires sudo)
sudo sb2p "vless://..." --tun
# Windows (run as Administrator)
sb2p "vless://..." --tun
```
> [!IMPORTANT]
> Very experimental, use at your own risk.
#### System Proxy
Automatically configure your OS to use the proxy.
```shell
# Set system proxy on start, restore on stop
sb2p "vless://..." --set-system-proxy
```
> [!NOTE]
> The system proxy settings will be restored to their original state when the `SingBoxProxy` instance is closed or goes out of scope, but multiple instances may interfere with each other, may be better to backup your initial settings before using this feature.
### Discaimer
I'm not responsible for possible misuse of this software. Please use it in accordance with the law and respect the terms of service of the services you access through proxies.
#### Consider leaving a star ⭐
[](https://github.com/nichind/singbox2proxy)
Raw data
{
"_id": null,
"home_page": null,
"name": "singbox2proxy",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "sing-box, hysteria2, v2ray, v2core, v2ray-core, proxy, vless, vmess, shadowsocks, trojan, python, cli",
"author": null,
"author_email": "nichind <nichind@proton.me>",
"download_url": "https://files.pythonhosted.org/packages/12/90/925a2d7646badedc1e42933e8cf3dff9f0a16d6d92e8100dcc64485323ca/singbox2proxy-0.2.3.tar.gz",
"platform": null,
"description": "## singbox2proxy \n\n[](https://pypi.org/project/singbox2proxy/)[](https://github.com/nichind/singbox2proxy/actions/workflows/build.yml) [](https://github.com/nichind/singbox2proxy/actions/workflows/publish.yml)\n\nIntegrate sing-box proxies into your python applications with ease on any device.\n\n- sing-box auto-install & easy management\n- zero dependencies for base functionality\n- seamless integration with existing applications\n- tuned for best performance and latency in mind\n\n### Supported Protocols\n\nThis module supports these sing-box protocols:\n\n- VMess (`vmess://`)\n- VLESS (`vless://`)\n- Shadowsocks (`ss://`)\n- Trojan (`trojan://`)\n- Hysteria2* (`hy2://`, `hysteria2://`)\n- Hysteria* (`hysteria://`)\n- TUIC* (`tuic://`)\n- WireGuard (`wg://`)\n- SSH (`ssh://`)\n- HTTP/HTTPS (`http://`, `https://`)\n- SOCKS (`socks://`, `socks4://`, `socks5://`)\n- NaiveProxy* (`naive+https://`)\n\n*: Chaining as a middle proxy not supported, according to the [sing-box docs](https://sing-box.sagernet.org/configuration/inbound/)\n\n### Installation\n\nwith pip\n\n```shell\npip install singbox2proxy \n```\n\nwith [uv](https://pypi.org/project/uv/)\n\n```shell\nuv pip install singbox2proxy \n```\n\nbuild from source\n\n```shell\ngit clone https://github.com/nichind/singbox2proxy.git\ncd singbox2proxy\npip install -e .\n```\n\n### Python Usage\n\nUsing built-in client powered by [curl-cffi](https://pypi.org/project/curl-cffi/) or [requests](https://pypi.org/project/requests/)\n\n```python\nfrom singbox2proxy import SingBoxProxy\n\nproxy = SingBoxProxy(\"vless://...\")\nresponse = proxy.request(\"GET\", \"https://api.ipify.org?format=json\") # IF curl-cffi is installed, it will be used; otherwise, requests will be used.\nprint(response.status_code, response.text) # 200, {\"ip\":\"...\"}\n```\n\nIntegrating with your own HTTP client\n\n```python\nimport requests\nfrom singbox2proxy import SingBoxProxy\n\nproxy = SingBoxProxy(\"hy2://...\")\nsession = requests.Session()\nsession.proxies = proxy.proxy_for_requests # {\"http\": \"http://127.0.0.1:<port>\", \"https\": \"http://127.0.0.1:<port>\"}\nresponse = session.get(\"https://api.ipify.org?format=json\")\nprint(response.status_code, response.text) # 200, {\"ip\":\"...\"}\n```\n\nExample with aiohttp\n\n```python\nfrom singbox2proxy import SingBoxProxy\nimport aiohttp\n\nasync def main():\n proxy = SingBoxProxy(\"vmess://...\")\n async with aiohttp.ClientSession(proxy=proxy.socks5_proxy_url or proxy.http_proxy_url) as session:\n async with session.get(\"https://api.ipify.org?format=json\") as response:\n print(response.status, await response.text()) # 200, {\"ip\":\"...\"}\n```\n\n#### Chaining\n\nChained proxies allow you to route your traffic through multiple proxy servers if you'll ever need more privacy or easy restriction bypass. You can chain multiple proxies together by specifying a `chain_proxy` with a gate `SingBoxProxy` instance when creating a new `SingBoxProxy`.\n\n> [!NOTE]\n> See what protocols can be used as middleman proxies at [supported protocols](#supported-protocols)\n\n```python\nfrom singbox2proxy import SingBoxProxy\n\nproxy1 = SingBoxProxy(\"vmess://...\")\nproxy2 = SingBoxProxy(\"vless://...\", chain_proxy=proxy1)\n\nresponse = proxy2.request(\"GET\", \"https://api.ipify.org?format=json\")\nprint(response.status_code, response.text) # 200, {\"ip\": \"<proxy2's IP>\"}\n# Here, requests made through `proxy2` will first go through `proxy1`, then proxy1 will forward the request to proxy2, and finally proxy2 will send the request to the target server.\n```\n\n#### TUN Mode (System-Wide VPN)\n\nCreate a virtual network interface to route all system traffic through the proxy. This requires root/administrator privileges.\n\n> [!IMPORTANT]\n> Very experimental, use at your own risk.\n\n```python\n# Requires root/admin privileges\nproxy = SingBoxProxy(\"vless://...\", tun_enabled=True)\n\n# All system traffic is now routed through the proxy\n# Use like a normal VPN connection\n```\n\n#### System Proxy Configuration\n\nAutomatically configure your OS proxy settings. This is a great alternative to TUN mode when you don't have root access.\n\n> [!NOTE]\n> The system proxy settings will be restored to their original state when the `SingBoxProxy` instance is closed or goes out of scope, but multiple instances may interfere with each other, may be better to backup your initial settings before using this feature.\n\n```python\n# Automatically sets system proxy and restores on exit\nwith SingBoxProxy(\"vless://...\", set_system_proxy=True) as proxy:\n # Your web browser and other apps will now use the proxy\n print(f\"System proxy configured to use {proxy.http_proxy_url}\")\n```\n\n### CLI\n\n> [!NOTE]\n> If the `singbox2proxy` or `sb2p` command isn't working in your terminal, use `python -m singbox2proxy <command>`, `uv run -m singbox2proxy <command>`, etc. instead.\n\n#### Basic Commands\n\nStart a single proxy:\n\n```shell\nsb2p \"vmess://eyJ2IjoiMiIsInBzIj...\"\n```\n\nSpecify custom ports:\n\n```shell\nsb2p \"ss://...\" --http-port 8080 --socks-port False # Socks disabled\n```\n\nTest the proxy connection:\n\n```shell\nsb2p \"trojan://...\" --test\n```\n\n#### Proxy Chaining\n\nChain multiple proxies (traffic flows: you -> proxy1 -> proxy2 -> target):\n\n```shell\nsb2p \"vmess://...\" \"vless://...\" \"hy2://...\" --chain\n```\n\n> [!NOTE]\n> See what protocols can be used as middleman proxies at [supported protocols](#supported-protocols)\n\nThe first URL becomes the entry point, and the last URL connects to the target server.\n\n#### Configuration Management\n\nGenerate configuration without starting:\n\n```shell\nsb2p \"vless://...\" --config-only\n```\n\nSave configuration to file:\n\n```shell\nsb2p \"vmess://...\" --output-config config.json\n```\n\n#### Logging Options\n\nEnable verbose logging:\n\n```shell\nsb2p \"ss://...\" --verbose\n```\n\nDisable all logging:\n\n```shell\nsb2p \"hy2://...\" --quiet\n```\n\n#### TUN Mode (System-Wide VPN)\n\nEnable TUN mode to route all system traffic through the proxy.\n\n```shell\n# Linux/macOS (requires sudo)\nsudo sb2p \"vless://...\" --tun\n\n# Windows (run as Administrator)\nsb2p \"vless://...\" --tun\n```\n\n> [!IMPORTANT]\n> Very experimental, use at your own risk.\n\n#### System Proxy\n\nAutomatically configure your OS to use the proxy.\n\n```shell\n# Set system proxy on start, restore on stop\nsb2p \"vless://...\" --set-system-proxy\n```\n\n> [!NOTE]\n> The system proxy settings will be restored to their original state when the `SingBoxProxy` instance is closed or goes out of scope, but multiple instances may interfere with each other, may be better to backup your initial settings before using this feature.\n\n### Discaimer\n\nI'm not responsible for possible misuse of this software. Please use it in accordance with the law and respect the terms of service of the services you access through proxies.\n\n#### Consider leaving a star \u2b50\n\n[](https://github.com/nichind/singbox2proxy)\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "\ud83d\udc33 Use sing-box (v2ray) proxies (VLESS + REALITY, VMess, Trojan, Shadowsocks, Hysteria, Hysteria2, TUIC, WireGuard, SSH) directly in your http clients, with chaining support and easy CLI",
"version": "0.2.3",
"project_urls": {
"Homepage": "https://github.com/nichind/singbox2proxy",
"Issues": "https://github.com/nichind/singbox2proxy/issues"
},
"split_keywords": [
"sing-box",
" hysteria2",
" v2ray",
" v2core",
" v2ray-core",
" proxy",
" vless",
" vmess",
" shadowsocks",
" trojan",
" python",
" cli"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "4432eb42ff8195ba0adb47e4caef5f484961c06074bb16e71b91883437491c3d",
"md5": "2a80a4eeabcbf942768f06bb2262e454",
"sha256": "1e07891bd2921ce7d738bc52aff6efce8c4518131e36da00e5a409c932b85f08"
},
"downloads": -1,
"filename": "singbox2proxy-0.2.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2a80a4eeabcbf942768f06bb2262e454",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 39386,
"upload_time": "2025-10-29T22:25:36",
"upload_time_iso_8601": "2025-10-29T22:25:36.482556Z",
"url": "https://files.pythonhosted.org/packages/44/32/eb42ff8195ba0adb47e4caef5f484961c06074bb16e71b91883437491c3d/singbox2proxy-0.2.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "1290925a2d7646badedc1e42933e8cf3dff9f0a16d6d92e8100dcc64485323ca",
"md5": "5a01f4b3931d0766df9bc0012173e6ad",
"sha256": "cf39e7e9089b3a873cdcd32691632098927d82e45b739a7b24482418d78c5604"
},
"downloads": -1,
"filename": "singbox2proxy-0.2.3.tar.gz",
"has_sig": false,
"md5_digest": "5a01f4b3931d0766df9bc0012173e6ad",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 40199,
"upload_time": "2025-10-29T22:25:37",
"upload_time_iso_8601": "2025-10-29T22:25:37.667745Z",
"url": "https://files.pythonhosted.org/packages/12/90/925a2d7646badedc1e42933e8cf3dff9f0a16d6d92e8100dcc64485323ca/singbox2proxy-0.2.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-29 22:25:37",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "nichind",
"github_project": "singbox2proxy",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "psutil",
"specs": [
[
"<=",
"7.1"
]
]
}
],
"lcname": "singbox2proxy"
}
JSON
