Development Status
- 6 - Mature
Environment
- Console
- Web Environment
Intended Audience
- Developers
Operating System
- MacOS
- Microsoft :: Windows
- OS Independent
- POSIX
- POSIX :: BSD :: FreeBSD
- POSIX :: Linux
- Unix
Programming Language
- Python :: 3
- Python :: 3.9
- Python :: 3.10
- Python :: 3.11
- Python :: 3.12
- Python :: 3.13
- Python :: Implementation :: CPython
- Python :: Implementation :: PyPy
Topic
- Database :: Database Engines/Servers
- Internet :: Proxy Servers
- Internet :: WWW/HTTP :: Dynamic Content
- Internet :: WWW/HTTP :: HTTP Servers
- Software Development :: Build Tools
- Software Development :: Testing
- Software Development :: Libraries :: Python Modules
pyngrok is a Python wrapper for ngrok that manages its own binary, making ngrok 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 the pyngrok client.
Installation
pyngrok is available on PyPI and can be installed
using pip:
pip install pyngrok
or conda:
conda install -c conda-forge pyngrok
That's it! pyngrok is now available as a package to your Python projects, and ngrok is now available from
the command line.
Basic Usage
Open a Tunnel
To open a tunnel, use the connect method,
which returns a NgrokTunnel, and this
returned object has a reference to the public URL generated by ngrok in its public_url
attribute.
from pyngrok import ngrok
# 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 file
named_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)
The connect method takes kwargs as well,
which allows
you to pass additional tunnel configurations that are supported by ngrok (or the name of a tunnel defined in
ngrok's config file), as documented here.
ngrok's API
The api method allows you to use the local
ngrok agent to make requests against the ngrok API, if you
have set an API key.
For example, here's how you would reserve a ngrok domain, then create a Cloud Endpoint with an associated traffic
policy:
from pyngrok import ngrok
domain = "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 default ngrok binary on your path, so all features of ngrok are
available on the command line.
ngrok http 80
For details on how to fully leverage ngrok from the command line,
see ngrok's official documentation.
Documentation
For more advanced usage, pyngrok's official documentation is available
on Read the Docs.
Integration Examples
Contributing
If you would like to get involved, be sure to review the Contribution Guide.
Want to contribute financially? If you've found pyngrok useful, sponsorship
would also be greatly appreciated!
