Skip to main content

Proxy server that can tunnel among remote servers by regex rules.

Project description

made-with-python PyPI-version Hit-Count Downloads

HTTP/Socks4/Socks5/Shadowsocks/ShadowsocksR/SSH/Redirect/Pf TCP/UDP asynchronous tunnel proxy implemented in Python3 asyncio.


$ pip3 install pproxy
Successfully installed pproxy-1.9.5
$ pproxy
Serving on :8080 by http,socks4,socks5
$ pproxy -l ss://chacha20:abc@:8080
Serving on :8080 by ss (chacha20-py)

Optional: (better performance with C ciphers)

$ pip3 install pproxy[accelerated]
Successfully installed pycryptodome-3.6.4

Apply OS system-wide proxy: (MacOS, Windows)

$ pproxy -r ss://chacha20:abc@server_ip:8080 --sys -vv
Serving on :8080 by http,socks4,socks5
System proxy setting -> socks5 localhost:8080
socks5 ::1:57345 -> ss server_ip:8080 ->
socks5 ::1:57345 -> ss server_ip:8080 ->
..... (all local traffic log) ......

Apply CLI proxy: (MacOS, Linux)

$ export http_proxy=http://localhost:8080
$ export https_proxy=http://localhost:8080

Run With Docker

pproxy Docker container has both python3 (with Cryptodome for performance optimizations) and pypy versions available.


docker run -it -p 8080:8080 mosajjal/pproxy:latest -l http://:8080 -vv


docker run -it -p 8080:8080 mosajjal/pproxy:latest-pypy -l http://:8080 -vv


  • Lightweight single-thread asynchronous IO.
  • Pure python, no additional library required.
  • Proxy client/server for TCP/UDP.
  • Schedule (load balance) among remote servers.
  • Incoming traffic auto-detect.
  • Tunnel/relay/backward-relay support.
  • Unix domain socket support.
  • User/password authentication support.
  • Filter/block hostname by regex patterns.
  • SSL/TLS client/server support.
  • Shadowsocks OTA (One-Time-Auth), SSR plugins.
  • Statistics by bandwidth and traffic.
  • PAC support for javascript configuration.
  • Iptables/Pf NAT redirect packet tunnel.
  • System proxy auto-setting support.
  • Client/Server API provided.


Name TCP server TCP client UDP server UDP client scheme
http (connect)     http://
http (get,post,etc)     httponly:// (as client)
https     http+ssl://
socks4     socks4://
socks5 ✔ udp-only ✔ udp-only socks5://
socks5 over TLS     socks5+ssl://
shadowsocks ss://
shadowsocks aead     ss://
shadowsocksR     ssr://
ssh tunnel       ssh://
iptables nat       redir://
pfctl nat (macos)       pf://
echo     echo://
tunnel (raw socket) tunnel:// tunnel{ip}://
websocket (simple tunnel)     ws:// ws{dst_ip}://
xxx over TLS     xxx+ssl://
AUTO DETECT     a+b+c+d://

Scheduling Algorithms

Name TCP UDP Parameter Default
first_available -s fa
round_robin -s rr  
random_choice -s rc  
least_connection   -s lc  


pycryptodome is an optional library to enable faster (C version) cipher. pproxy has many built-in pure python ciphers. They are lightweight and stable, but slower than C ciphers. After speedup with PyPy, pure python ciphers can get similar performance as C version. If the performance is important and don’t have PyPy, install pycryptodome instead.

asyncssh is an optional library to enable ssh tunnel client support.

These are some performance benchmarks between Python and C ciphers (dataset: 8M):

chacha20-c 0.64 secs
chacha20-py (pypy3) 1.32 secs
chacha20-py 48.86 secs

PyPy3 Quickstart:

$ pypy3 -m ensurepip
$ pypy3 -m pip install asyncio pproxy


$ pproxy -h
usage: pproxy [-h] [-l LISTEN] [-r RSERVER] [-ul ULISTEN] [-ur URSERVER]
              [-b BLOCK] [-a ALIVED] [-v] [--ssl SSLFILE] [--pac PAC]
              [--get GETS] [--sys] [--test TESTURL] [--version]

Proxy server that can tunnel among remote servers by regex rules. Supported
protocols: http,socks4,socks5,shadowsocks,shadowsocksr,redirect,pf,tunnel

optional arguments:
  -h, --help        show this help message and exit
  -l LISTEN         tcp server uri (default: http+socks4+socks5://:8080/)
  -r RSERVER        tcp remote server uri (default: direct)
  -ul ULISTEN       udp server setting uri (default: none)
  -ur URSERVER      udp remote server uri (default: direct)
  -b BLOCK          block regex rules
  -a ALIVED         interval to check remote alive (default: no check)
  -s {fa,rr,rc,lc}  scheduling algorithm (default: first_available)
  -v                print verbose output
  --ssl SSLFILE     certfile[,keyfile] if server listen in ssl mode
  --pac PAC         http PAC path
  --get GETS        http custom {path,file}
  --sys             change system proxy setting (mac, windows)
  --test TEST       test this url for all remote proxies and exit
  --version         show program's version number and exit

Online help: <>

URI Syntax

  • scheme

    • Currently supported scheme: http, socks, ss, ssl, secure. You can use + to link multiple protocols together.

      http http protocol (CONNECT)
      httponly http protocol (GET/POST)
      socks4 socks4 protocol
      socks5 socks5 protocol
      ss shadowsocks protocol
      ssr shadowsocksr (SSR) protocol
      ssh ssh client tunnel
      redir redirect (iptables nat)
      pf pfctl (macos pf nat)
      ssl unsecured ssl/tls (no cert)
      secure secured ssl/tls (cert)
      tunnel raw connection
      ws websocket connection
      echo echo-back service
      direct direct connection
    • http://” accepts GET/POST/CONNECT as server, sends CONNECT as client. “httponly://” sends “GET/POST” as client, works only on http traffic.

    • Valid schemes: http://, http+socks4+socks5://, http+ssl://, ss+secure://, http+socks5+ss://

    • Invalid schemes: ssl://, secure://

  • cipher

    • Cipher’s format: “cipher_name:cipher_key”. Cipher can be base64-encoded. So cipher string with “YWVzLTEyOC1nY206dGVzdA==” is equal to “aes-128-gcm:test”.

    • Full cipher support list:

      Cipher Key Length IV Length Score (0-5)
      table-py any 0 0 (lowest)
      rc4 16 0 0 (lowest)
      rc4-md5 16 16 0.5
      chacha20 32 8 5 (highest)
      chacha20-ietf 32 12 5
      chacha20-ietf- poly1305-py 32 32 AEAD
      salsa20 32 8 4.5




      16 16






      24 16








      32 16



























      bf-cfb 16 8 1
      cast5-cfb 16 8 2.5
      des-cfb 8 8 1.5
      rc2-cfb-py 16 8 2
      idea-cfb-py 16 8 2.5
      seed-cfb-py 16 16 2
    • pproxy ciphers have pure python implementations. Program will switch to C cipher if there is C implementation available within pycryptodome. Otherwise, use pure python cipher.

    • AEAD ciphers use additional payload after each packet. The underlying protocol is different. Specifications: AEAD.

    • Some pure python ciphers (aes-256-cfb1-py) is quite slow, and is not recommended to use without PyPy speedup. Try install pycryptodome and use C version cipher instead.

    • To enable OTA encryption with shadowsocks, add ‘!’ immediately after cipher name.

  • netloc

    • It can be “hostname:port” or “/unix_domain_socket”. If the hostname is empty, server will listen on all interfaces.
    • Valid netloc: localhost:8080,, /tmp/domain_socket, :8123
  • localbind

    • It can be “@in” or @ipv4_address or @ipv6_address
    • Valid localbind: @in, @, @::1
  • plugins

    • It can be multiple plugins joined by “,”. Supported plugins: plain, origin, http_simple, tls1.2_ticket_auth, verify_simple, verify_deflate
    • Valid plugins: /,tls1.2_ticket_auth,verify_simple
  • rules

    • The filename that contains regex rules
  • auth

    • The username, colon ‘:’, and the password

URIs can be joined by “__” to indicate tunneling by relay. For example, ss:// make remote connection to the first shadowsocks proxy server, and then tunnel to the second http proxy server.

Client API

  • TCP Client API

    import asyncio, pproxy
    async def test_tcp(proxy_uri):
        conn = pproxy.Connection(proxy_uri)
        reader, writer = await conn.tcp_connect('', 80)
        writer.write(b'GET / HTTP/1.1\r\n\r\n')
        data = await*16)
  • UDP Client API

    import asyncio, pproxy
    async def test_udp(proxy_uri):
        conn = pproxy.Connection(proxy_uri)
        answer = asyncio.Future()
        await conn.udp_sendto('', 53, b'hello the world', answer.set_result)
        await answer

Server API

  • Server API example:

    import asyncio
    import pproxy
    server = pproxy.Server('ss://')
    remote = pproxy.Connection('ss://')
    args = dict( rserver = [remote],
                 verbose = print )
    loop = asyncio.get_event_loop()
    handler = loop.run_until_complete(server.start_server(args))
    except KeyboardInterrupt:


  • Regex rule

    Define regex file “rules” as follow:

    #google domains

    Then start pproxy

    $ pproxy -r -vv
    Serving on :8080 by http,socks4,socks5
    http ::1:57768 -> http ->
    http ::1:57772 ->
    socks4 ::1:57770 -> http ->

    pproxy will serve incoming traffic by http/socks4/socks5 auto-detect protocol, redirect all google traffic to http proxy, and visit all other traffic directly from local.

  • Use cipher

    Add cipher encryption to make sure data can’t be intercepted. Run pproxy locally as:

    $ pproxy -l ss://:8888 -r ss:// -vv

    Next, run remotely on server “”. The base64 encoded string of “chacha20:cipher_key” is also supported:

    $ pproxy -l ss://chacha20:cipher_key@:12345

    The same as:

    $ pproxy -l ss://Y2hhY2hhMjA6Y2lwaGVyX2tleQ==@:12345

    The traffic between local and is encrypted by stream cipher Chacha20 with secret key “cipher_key”.

  • Unix domain socket

    A more complex example:

    $ pproxy -l ss://salsa20!:complex_cipher_key@/tmp/pproxy_socket -r http+ssl://

    pproxy listen on the unix domain socket “/tmp/pproxy_socket” with cipher “salsa20” and key “complex_cipher_key”. OTA packet protocol is enabled by adding ! after cipher name. The traffic is tunneled to remote https proxy with simple http authentication.

  • SSL/TLS server

    If you want to listen in SSL/TLS, you must specify ssl certificate and private key files by parameter “–ssl”:

    $ pproxy -l http+ssl:// -l --ssl server.crt,server.key --pac /autopac

    pproxy listen on both 80 HTTP and 443 HTTPS ports, use the specified SSL/TLS certificate and private key files. The “–pac” enable PAC feature, so you can put “” path in your device’s auto-configure url.

    Simple guide for generating self-signed ssl certificates:

    $ openssl genrsa -des3 -out server.key 1024
    $ openssl req -new -key server.key -out server.csr
    $ cp server.key
    $ openssl rsa -in -out server.key
    $ openssl x509 -req -days 365 -in server.csr -signkey server.key -out server.crt
  • SSR plugins

    ShadowsocksR example with plugin “tls1.2_ticket_auth” to emulate common tls traffic:

    $ pproxy -l ssr://chacha20:mypass@,tls1.2_ticket_auth,verify_simple
  • Local bind ip

    If you want to route the traffic by different local bind, use the @localbind URI syntax. For example, server has three ip interfaces:,, You want to route traffic matched by “rule1” to and traffic matched by “rule2” to, and the remaining traffic directly:

    $ pproxy -l ss://:8000/@in -r ss:// -r ss://
  • Redirect/Pf protocol

    IPTable NAT redirect example (Ubuntu):

    $ sudo iptables -t nat -A OUTPUT -p tcp --dport 80 -j REDIRECT --to-ports 5555
    $ pproxy -l redir://:5555 -r http://remote_http_server:3128 -vv

    The above example illustrates how to redirect all local output tcp traffic with destination port 80 to localhost port 5555 listened by pproxy, and then tunnel the traffic to remote http proxy.

    PF redirect example (MacOS):

    $ sudo pfctl -ef /dev/stdin
    rdr pass on lo0 inet proto tcp from any to any port 80 -> port 8080
    pass out on en0 route-to lo0 inet proto tcp from any to any port 80 keep state
    $ sudo pproxy -l pf://:8080 -r socks5://remote_socks5_server:1324 -vv

    Make sure pproxy runs in root mode (sudo), otherwise it cannot redirect pf packet.

  • Relay tunnel

    Relay tunnel example:

    $ pproxy -r http://server1__ss://server2__socks://server3

    pproxy will connect to server1 first, tell server1 connect to server2, and tell server2 connect to server3, and make real traffic by server3.

  • Raw connection tunnel

    TCP raw connection tunnel example:

    $ pproxy -l tunnel{}://:80
    $ curl -H "Host:" http://localhost

    UDP dns tunnel example:

    $ pproxy -ul tunnel{}://:53
    $ nslookup localhost
  • UDP more complicated example

    Run the shadowsocks udp proxy on remote machine:

    $ pproxy -ul ss://remote_server:13245

    Run the commands on local machine:

    $ pproxy -ul tunnel{}://:53 -ur ss://remote_server:13245 -vv
    UDP tunnel -> ss remote_server:13245 ->
    UDP tunnel -> ss remote_server:13245 ->
    $ nslookup localhost
  • Load balance example

    Specify multiple -r server, and a scheduling algorithm (rr = round_robin, rc = random_choice, lc = least_connection):

    $ pproxy -r http://server1 -r ss://server2 -r socks5://server3 -s rr -vv
    http ::1:42356 -> http server1 ->
    http ::1:42357 -> ss server2 ->
    http ::1:42358 -> socks5 server3 ->
    http ::1:42359 -> http server1 ->
    $ pproxy -ul tunnel://:53 -ur tunnel:// -ur tunnel:// -s rc -vv
    UDP tunnel ::1:35378 -> tunnel
    UDP tunnel ::1:35378 -> tunnel
  • WebSocket example

    WebSocket protocol is similar to Tunnel protocol. It is raw and doesn’t support any proxy function. It can connect to other proxy like Tunnel protocol.

    First run pproxy on remote machine:

    $ pproxy -l ws://:80 -r tunnel:///tmp/myproxy -v
    $ pproxy -l ss://chacha20:abc@/tmp/myproxy -v

    Run pproxy on local machine:

    $ pproxy -l tunnel://:1234 -r ws://remote_ip:80 -vv

    Then port :1234 on local machine is connected to the /tmp/myproxy on remote machine by WebSocket tunnel. You can specify any proxy protocol details on /tmp/myproxy.

    It is a good practice to use some CDN in the middle of local/remote machines. CDN with WebSocket support can hide remote machine’s real IP from public.

  • Backward proxy

    Sometimes, the proxy server hides behind an NAT router and doesn’t have a public ip. The client side has a public ip “client_ip”. Backward proxy feature enables the server to connect backward to client and wait for proxy requests.

    Run pproxy client as follows:

    $ pproxy -l http://:8080 -r http+in://:8081 -v

    Run pproxy server as follows:

    $ pproxy -l http+in://client_ip:8081

    Server connects to client_ip:8081 and waits for client proxy requests. The protocol http specified is just an example. It can be any protocol and cipher pproxy supports. The scheme “in” should exist in URI to inform pproxy that it is a backward proxy.

  • SSH client tunnel

    SSH client tunnel support is enabled by installing additional library asyncssh. After “pip3 install asyncssh”, you can specify “ssh” as scheme to proxy via ssh client tunnel.

    $ pproxy -l http://:8080 -r ssh://

    If a client private key is used to authenticate, put double colon “::” between login and private key path.

    $ pproxy -l http://:8080 -r ssh://

    SSH connection known_hosts feature is disabled by default.


  • python-esp - Pure python VPN (IPSec,IKE,IKEv2,L2TP)
  • shadowproxy - Another awesome proxy implementation by guyingbo

Project details

Release history Release notifications

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for pproxy, version 2.2.0
Filename, size File type Python version Upload date Hashes
Filename, size pproxy-2.2.0-py3-none-any.whl (37.0 kB) File type Wheel Python version py3 Upload date Hashes View hashes
Filename, size pproxy-2.2.0.tar.gz (44.2 kB) File type Source Python version None Upload date Hashes View hashes

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN SignalFx SignalFx Supporter DigiCert DigiCert EV certificate StatusPage StatusPage Status page