pyngrok - a Python wrapper for ngrok
pyngrok is a Python wrapper for ngrok that manages its own binary and puts
it on our path, making
ngrok readily available from anywhere on the command line and via a
convenient Python API.
pyngrok is available on PyPI and can be installed
pip install pyngrok
open a tunnel
To open a tunnel, use the
connect() method, which returns the public URL generated by
from pyngrok import ngrok # Open a tunnel on the default port 80 public_url = ngrok.connect()
connect() method can also take an
options parameter, which allows us to pass additional
options that are supported by ngrok.
get active tunnels
It can be useful to ask the
ngrok client what tunnels are currently open. This can be
accomplished with the
get_tunnels() method, which returns a list of
from pyngrok import ngrok tunnels = ngrok.get_tunnels() # A public ngrok URL that tunnels to port 80 (ex. http://<public_sub>.ngrok.io) public_url = tunnels.public_url
closing a tunnel
All open tunnels will automatically be closed when the Python process terminates, but we can also close them manually.
from pyngrok import ngrok public_url = "http://<public_sub>.ngrok.io" ngrok.disconnect(public_url)
the ngrok process
Opening a tunnel will start the
ngrok process. This process will remain alive, and the tunnels
ngrok.kill() is invoked, or until the Python process terminates.
If we are building a short-lived app, for instance a CLI, we may want to block on the
process so tunnels stay open until the user intervenes. We can do that by accessing the
from pyngrok import ngrok ngrok_process = ngrok.get_ngrok_process() # Block until CTRL-C or some other terminating event ngrok_process.process.wait()
NgrokProcess also contains an
api_url variable, usually initialized to
http://127.0.0.1:4040, from which we can access the ngrok client API.
If some feature we need is not available in this package, the client API is accessible to us via the
api_request() method. Additionally, the
NgrokTunnel objects expose a
uri variable, which contains
the relative path used to manipulate that resource against the client API. This package also gives us
ngrok from the command line, as shown below.
other useful configuration
ngrok with an auth token enables additional features available on our account (for
instance, the ability to open more tunnels concurrently). We can obtain our auth token from
the ngrok dashboard and install it like this:
from pyngrok import ngrok ngrok.set_auth_token("<NGROK_AUTH_TOKEN>") # Once an auth token is set, we are able to open multiple tunnels at the same time ngrok.connect() ngrok.connect(8000)
This will set the auth token in the config file. We can also set it in a one-off fashion by
setting it for the "auth" key of the
ngrok config file lives in the home
.ngrok2 folder. We can change this in one of two ways. Either pass the
config_path parameter to methods:
from pyngrok import ngrok CONFIG_PATH = "/opt/ngrok/config.yml" ngrok.connect(config_path=CONFIG_PATH)
or override the
from pyngrok import ngrok ngrok.DEFAULT_CONFIG_PATH = "/opt/ngrok/config.yml" ngrok.set_auth_token("<NGROK_AUTH_TOKEN>")
pyngrok package manages its own
ngrok binary. However, we can use our
ngrok binary if we
want in one of two ways. Either pass the
ngrok_path parameter to methods:
from pyngrok import ngrok NGROK_PATH = "/usr/local/bin/ngrok" ngrok.get_tunnels(ngrok_path=NGROK_PATH)
or override the
from pyngrok import ngrok ngrok.DEFAULT_NGROK_PATH = "/usr/local/bin/ngrok" ngrok.connect()
command line usage
This package puts the default
ngrok binary on our path, so all features of
ngrok are also
available on the command line.
ngrok http 80
For details on how to fully leverage command line usage, see ngrok's official documentation.
If you find issues, report them on GitHub. Pull requests for fixes and features are also warmly welcomed.