Skip to main content

Asynchronous I/O HTTP and HTTPS Proxy on Python >= 3.6

Project description

Wormhole is a forward proxy without caching. You may use it for:

  • Modifying requests to look like they are originated from the IP address that Wormhole is running on.

  • Adding an authentication layer to the internet users in your organization.

  • Logging internet activities to your syslog server.


  • Python >= 3.6

  • uvloop (optional)

Docker Image Usage

Run without authentication

$ docker pull bashell/wormhole
$ docker run -d -p 8800:8800 bashell/wormhole

Run with authentication

  • Create an empty directory on your docker host

  • Create an authentication file that contains username and password in this format username:password

  • Link that directory to the container via option -v and also run wormhole container with option -a /path/to/authentication_file


$ docker pull bashell/wormhole
$ mkdir -p /path/to/dir
$ echo "user1:password1" > /path/to/dir/wormhole.passwd
$ docker run -d -v /path/to/dir:/opt/wormhole \
  -p 8800:8800 bashell/wormhole \
  -a /opt/wormhole/wormhole.passwd

How to install

Stable Version

Please install the stable version using pip command:

$ pip install wormhole-proxy

Development Snapshot

You can install the development snapshot using pip with mercurial:

$ pip install hg+

Or install from your local clone:

$ hg clone
$ cd wormhole/
$ pip install -e .

You can also install the latest tip snapshot using the following command:

$ pip install

How to use

  1. Run wormhole command

    $ wormhole
  2. Set browser’s proxy setting to

    port: 8800

Command help

$ wormhole --help


MIT License (included in


  • This project is forked and converted to Mercurial from WARP on GitHub.

  • Authentication file contains username and password in plain text, keep it secret! (I will try to encrypt/encode it soon.)

  • Wormhole may not work in:

    • some ISPs

    • some firewalls

    • some browers

    • some web sites

Project details

Download files

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

Source Distribution

wormhole-proxy-3.0.2.tar.gz (9.8 kB view hashes)

Uploaded source

Built Distribution

wormhole_proxy-3.0.2-py3.10.egg (21.3 kB view hashes)

Uploaded 3 0 2

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page