tun2socks-python

Python bindings for tun2socks.

Installation

Install the package from PyPI:

pip install tun2socks

The published binary wheels include the compiled Go backend and native Python binding. A compatible wheel is selected automatically, so installing on a supported platform does not require Go, CMake, or a C/C++ compiler.

Binary Wheel Support

Platform	Architecture	CPython versions
Linux (manylinux2014)	x86_64	3.8-3.14, 3.13t, 3.14t
Linux (manylinux2014)	ARM64	3.8-3.14, 3.13t, 3.14t
Windows	x86_64	3.8-3.14, 3.13t, 3.14t
Windows	ARM64	3.9-3.14, 3.13t, 3.14t
macOS	Intel	3.8-3.14, 3.13t, 3.14t
macOS	Apple Silicon	3.8-3.14, 3.13t, 3.14t

Windows ARM64 starts at Python 3.9 because cibuildwheel does not provide a CPython 3.8 Windows ARM64 build.

Building from Source

Building from source is only necessary for contributors or when no compatible wheel is available. It requires:

• Go
• CMake 3.15 or newer
• A C/C++ toolchain: GCC on Linux, Apple Clang on macOS, MinGW-w64 on Windows x86_64, or LLVM-MinGW on Windows ARM64

API

>>> import tun2socks
>>> help(tun2socks) Help on package tun2socks: NAME
tun2socks
PACKAGE CONTENTS
tun2socks
FUNCTIONS
startFromArgs(...) method of builtins.PyCapsule instance
startFromArgs(device: str, networkInterface: str, logLevel: str,
proxy: str, restAPI: str, tcpSendBufferSize: str = '',
tcpReceiveBufferSize: str = '', tcpAutoTuning: bool = False) -> None
Start tun2socks with custom arguments

Runtime provenance is available as tun2socks.__version__, tun2socks.__upstream_version__, and tun2socks.__upstream_commit__.

Vendored Upstream Source

The source distribution vendors an exact stable tun2socks release so source installs do not depend on Git submodule support. Every upstream-owned file under tun2socks-go is verified against the exact tag and commit recorded in UPSTREAM_VERSION and UPSTREAM_COMMIT. The sole binding-owned addition inside that tree is tun2socks-go/python-binding/main.go; it provides the C archive entry point without modifying upstream source.

Stable upstream releases are checked daily by GitHub Actions and can be selected explicitly through manual dispatch. The synchronization tooling rejects drafts, prereleases, unexpected vendor changes, and future upstream collisions with the binding path. Run the integrity check locally with:

python scripts/sync-tun2socks.py verify

The Python package version is stored independently in VERSION because downstream-only packaging revisions use a fourth version component, such as 2.7.0.1.

License

The license for this project follows its original go repository tun2socks and is under MIT.

(Upstream project relicensed, see tun2socks#460)