<p align="center"><img alt="pyngrok - a Python wrapper for ngrok" src="https://pyngrok.readthedocs.io/en/latest/_images/logo.png" /></p>

[![PyPI version](https://badge.fury.io/py/pyngrok.svg)](https://badge.fury.io/py/pyngrok)
[![Build Status](https://travis-ci.org/alexdlaird/pyngrok.svg?branch=master)](https://travis-ci.org/alexdlaird/pyngrok)
[![codecov](https://codecov.io/gh/alexdlaird/pyngrok/branch/master/graph/badge.svg)](https://codecov.io/gh/alexdlaird/pyngrok)
[![Documentation Status](https://readthedocs.org/projects/pyngrok/badge/?version=latest)](https://pyngrok.readthedocs.io/en/latest/?badge=latest)
[![image](https://img.shields.io/pypi/pyversions/pyngrok.svg)](https://pypi.org/project/pyngrok/)
[![PyPI license](https://img.shields.io/pypi/l/pyngrok.svg)](https://pypi.org/project/pyngrok/)
[![Tweet](https://img.shields.io/twitter/url/http/shields.io.svg?style=social)](https://twitter.com/intent/tweet?text=Check+out+%23pyngrok%2C+a+Python+wrapper+for+%23ngrok+that+lets+you+programmatically+open+secure+%23tunnels+to+local+web+servers%2C+build+%23webhook+integrations%2C+enable+SSH+access%2C+test+chatbots%2C+demo+from+your+own+machine%2C+and+more.%0D%0A%0D%0A&url=https://github.com/alexdlaird/pyngrok&via=alexdlaird)

`pyngrok` is a Python wrapper for `ngrok` that manages its own binary and puts
it on your path, making `ngrok` readily available from anywhere on the command line and via a
convenient Python API.

[ngrok](https://ngrok.com) is a reverse proxy tool that opens secure tunnels from public URLs to localhost, perfect
for exposing local web servers, building webhook integrations, enabling SSH access, testing chatbots, demoing from
your own machine, and more, and its made even more powerful with native Python integration through `pyngrok`.

## Installation

`pyngrok` is available on [PyPI](https://pypi.org/project/pyngrok/) and can be installed
using `pip`:

```sh
pip install pyngrok
```

or `conda`:

```sh
conda install -c conda-forge pyngrok
```

That's it! `pyngrok` is now available as a package to our Python projects, and `ngrok` is now available from
the command line.

## 4.1.x to 5.0.0

The next release, 5.0.0, contains breaking changes, including dropping support for Python 2.7. 4.2.x is meant to ease
migration between 4.1.x and 5.0.0 and should not be pinned, as it will not be supported after 5.0.0 is released. To
prepare for these breaking changes, [see the changelog](https://github.com/alexdlaird/pyngrok/blob/master/CHANGELOG.md#420---2020-10-11).
To avoid these breaking changes altogether, or if Python 2.7 support is still needed, pin `pyngrok>=4.1,<4.2`.

## Basic Usage

To open a tunnel, use the [`connect`](https://pyngrok.readthedocs.io/en/latest/api.html#pyngrok.ngrok.connect) method,
which returns the public URL generated by `ngrok`.

```python
from pyngrok import ngrok

# Open a HTTP tunnel on the default port 80
public_url = ngrok.connect()
# Open a SSH tunnel
ssh_url = ngrok.connect(22, "tcp")
```

The [`connect`](https://pyngrok.readthedocs.io/en/latest/api.html#pyngrok.ngrok.connect) method takes an optional
`options` parameter, which allows us to pass additional properties that are [supported by ngrok](https://ngrok.com/docs#tunnel-definitions).

This package puts the default `ngrok` binary on our path, so all features of `ngrok` are
available on the command line.

```sh
ngrok http 80
```

For details on how to fully leverage `ngrok` from the command line, see [ngrok's official documentation](https://ngrok.com/docs).

### Python 2.7

The last version of `pyngrok` that supports Python 2.7 is 4.1.x, so we need to pin `pyngrok>=4.1,<4.2` if we still want
to use `pyngrok` with this version of Python.

## Documentation

For more advanced usage, `pyngrok`'s official documentation is available at [http://pyngrok.readthedocs.io](http://pyngrok.readthedocs.io).

## Contributing

If you would like to get involved, be sure to review the [Contribution Guide](https://github.com/alexdlaird/pyngrok/blob/master/CONTRIBUTING.rst).

Want to contribute financially? If you've found `pyngrok` useful, [a donation](https://www.paypal.me/alexdlaird>) would
also be greatly appreciated!
