pyngrok is a Python wrapper forngrok that manages its own binary, makingngrok available via a convenient Python API and the command line.

ngrok is a reverse proxy that opens secure tunnels from public URLs to localhost. It's perfect for rapid development (test webhooks, demo local websites, enable SSH access), establishing ingress to external networks and devices, building production APIs (traffic policies, OAuth, load balancing), and more. And it's made even more powerful with native Python integration through thepyngrok client.

Installation

pyngrok is available onPyPI and can be installed usingpip:

pipinstallpyngrok

orconda:

condainstall-c conda-forge pyngrok

That's it!pyngrok is now available as a package to your Python projects, andngrok is now available from the command line.

Basic Usage

Open a Tunnel

To open a tunnel, use theconnect method, which returns aNgrokTunnel, and this returned object has a reference to the public URL generated byngrok in itspublic_url attribute.

frompyngrokimportngrok# Open a HTTP tunnel on the default port 80# <NgrokTunnel: "https://<public_sub>.ngrok.io" -> "http://localhost:80">http_tunnel=ngrok.connect()# Open a SSH tunnel# <NgrokTunnel: "tcp://0.tcp.ngrok.io:12345" -> "localhost:22">ssh_tunnel=ngrok.connect("22","tcp")# Open a named tunnel from the config filenamed_tunnel=ngrok.connect(name="my-config-file-tunnel")# Open an Internal Endpoint that's load balanced# <NgrokTunnel: "https://some-endpoint.internal" -> "http://localhost:9000">internal_endpoint=ngrok.connect(addr="9000",domain="some-endpoint.internal",pooling_enabled=True)

Theconnect method takeskwargs as well, which allows you to pass additional tunnel configurations that are supported byngrok (or thename of a tunnel defined inngrok's config file),as documented here.

ngrok's API

Theapi method allows you to use the localngrok agent to make requests againstthengrok API, if you haveset an API key. For example, here's how you would reserve angrok domain, then create a Cloud Endpoint with an associated traffic policy:

frompyngrokimportngrokdomain="some-domain.ngrok.dev"ngrok.api("reserved-domains","create","--domain",domain)ngrok.api("endpoints","create","--bindings","public","--url",f"https://{domain}","--traffic-policy-file","policy.yml")

Command Line Usage

This package puts the defaultngrok binary on your path, so all features ofngrok are available on the command line.

ngrok http 80

For details on how to fully leveragengrok from the command line, seengrok's official documentation.

Documentation

For more advanced usage,pyngrok's official documentation is available onRead the Docs.

Integration Examples

• Flask
• Django
• Docker
• Google Colab
• End-to-End Testing

Contributing

If you would like to get involved, be sure to review theContribution Guide.

Want to contribute financially? If you've foundpyngrok useful,sponsorship would also be greatly appreciated!