Skip to main content
Help us improve PyPI by participating in user testing. All experience levels needed!

Asynchronous I/O HTTP and HTTPS Proxy on Python 3.5

Project description

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

  • 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.5.0
  • 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 default 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

Release history Release notifications

This version
History Node


History Node


Download files

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

Filename, size & hash SHA256 hash help File type Python version Upload date
wormhole-proxy-2.0.2.tar.gz (9.6 kB) Copy SHA256 hash SHA256 Source None May 25, 2016

Supported by

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