| Name | pyngrok JSON |
| Version |
7.2.12
JSON |
| download |
| home_page | None |
| Summary | A Python wrapper for ngrok |
| upload_time | 2025-07-09 19:17:54 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.8 |
| license | MIT License
Copyright (c) 2018-2025 Alex Laird
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
|
| keywords |
tunnel
webhook
reverse-proxy
ngrok
localhost
localtunnel
ingress
tunneling
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
<p align="center"><img alt="pyngrok - a Python wrapper for ngrok" src="https://pyngrok.readthedocs.io/en/latest/_images/logo.png" /></p>
[](https://pypi.org/project/pyngrok)
[](https://pypi.org/project/pyngrok)
[](https://codecov.io/gh/alexdlaird/pyngrok)
[](https://github.com/alexdlaird/pyngrok/actions/workflows/build.yml)
[](https://app.codacy.com/gh/alexdlaird/pyngrok/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade)
[](https://pyngrok.readthedocs.io/en/latest)
[](https://github.com/alexdlaird/pyngrok/blob/main/LICENSE)
`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`](https://ngrok.com) 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](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 your Python projects, and `ngrok` is now available from
the command line.
## Basic Usage
### Open a Tunnel
To open a tunnel, use the [`connect`](https://pyngrok.readthedocs.io/en/latest/api.html#pyngrok.ngrok.connect) method,
which returns a [`NgrokTunnel`](https://pyngrok.readthedocs.io/en/latest/api.html#pyngrok.ngrok.NgrokTunnel), and this
returned object has a reference to the public URL generated by `ngrok` in its [`public_url`](https://pyngrok.readthedocs.io/en/latest/api.html#pyngrok.ngrok.NgrokTunnel.public_url)
attribute.
```python
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`](https://pyngrok.readthedocs.io/en/latest/api.html#pyngrok.ngrok.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](https://pyngrok.readthedocs.io/en/latest/#tunnel-configurations).
### `ngrok`'s API
The [`api`](https://pyngrok.readthedocs.io/en/latest/api.html#pyngrok.ngrok.api) method allows you to use the local
`ngrok` agent to make requests against [the `ngrok` API](https://ngrok.com/docs/agent/cli-api/), if you
have [set an API key](https://pyngrok.readthedocs.io/en/latest/#setting-the-authtoken-or-api-key).
For example, here's how you would reserve a `ngrok` domain, then create a Cloud Endpoint with an associated traffic
policy:
```python
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.
```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/agent/cli/).
## Documentation
For more advanced usage, `pyngrok`'s official documentation is available
on [Read the Docs](https://pyngrok.readthedocs.io).
### Integration Examples
- [Flask](https://pyngrok.readthedocs.io/en/latest/integrations.html#flask)
- [Django](https://pyngrok.readthedocs.io/en/latest/integrations.html#django)
- [Docker](https://pyngrok.readthedocs.io/en/latest/integrations.html#docker)
- [Google Colab](https://pyngrok.readthedocs.io/en/latest/integrations.html#google-colaboratory)
- [End-to-End Testing](https://pyngrok.readthedocs.io/en/latest/integrations.html#end-to-end-testing)
## Contributing
If you would like to get involved, be sure to review
the [Contribution Guide](https://github.com/alexdlaird/pyngrok/blob/main/CONTRIBUTING.rst).
Want to contribute financially? If you've found `pyngrok` useful, [sponsorship](https://github.com/sponsors/alexdlaird)
would also be greatly appreciated!
Raw data
{
"_id": null,
"home_page": null,
"name": "pyngrok",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "Alex Laird <contact@alexlaird.com>",
"keywords": "tunnel, webhook, reverse-proxy, ngrok, localhost, localtunnel, ingress, tunneling",
"author": null,
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/64/7a/6f96513de7cadd81858b4e2bb8a31052b552cb21baeec305a5d0cac94a25/pyngrok-7.2.12.tar.gz",
"platform": null,
"description": "<p align=\"center\"><img alt=\"pyngrok - a Python wrapper for ngrok\" src=\"https://pyngrok.readthedocs.io/en/latest/_images/logo.png\" /></p>\n\n[](https://pypi.org/project/pyngrok)\n[](https://pypi.org/project/pyngrok)\n[](https://codecov.io/gh/alexdlaird/pyngrok)\n[](https://github.com/alexdlaird/pyngrok/actions/workflows/build.yml)\n[](https://app.codacy.com/gh/alexdlaird/pyngrok/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade)\n[](https://pyngrok.readthedocs.io/en/latest)\n[](https://github.com/alexdlaird/pyngrok/blob/main/LICENSE)\n\n`pyngrok` is a Python wrapper for `ngrok` that manages its own binary, making `ngrok` available via a convenient Python\nAPI and the command line.\n\n[`ngrok`](https://ngrok.com) is a reverse proxy that opens secure tunnels from public URLs to localhost. It's perfect\nfor rapid\ndevelopment (test webhooks, demo local websites, enable SSH access), establishing ingress to external\nnetworks and devices, building production APIs (traffic policies, OAuth, load balancing), and more. And\nit's made even more powerful with native Python integration through the `pyngrok` client.\n\n## Installation\n\n`pyngrok` is available on [PyPI](https://pypi.org/project/pyngrok/) and can be installed\nusing `pip`:\n\n```sh\npip install pyngrok\n```\n\nor `conda`:\n\n```sh\nconda install -c conda-forge pyngrok\n```\n\nThat's it! `pyngrok` is now available as a package to your Python projects, and `ngrok` is now available from\nthe command line.\n\n## Basic Usage\n\n### Open a Tunnel\n\nTo open a tunnel, use the [`connect`](https://pyngrok.readthedocs.io/en/latest/api.html#pyngrok.ngrok.connect) method,\nwhich returns a [`NgrokTunnel`](https://pyngrok.readthedocs.io/en/latest/api.html#pyngrok.ngrok.NgrokTunnel), and this\nreturned object has a reference to the public URL generated by `ngrok` in its [`public_url`](https://pyngrok.readthedocs.io/en/latest/api.html#pyngrok.ngrok.NgrokTunnel.public_url)\nattribute.\n\n```python\nfrom pyngrok import ngrok\n\n# Open a HTTP tunnel on the default port 80\n# <NgrokTunnel: \"https://<public_sub>.ngrok.io\" -> \"http://localhost:80\">\nhttp_tunnel = ngrok.connect()\n\n# Open a SSH tunnel\n# <NgrokTunnel: \"tcp://0.tcp.ngrok.io:12345\" -> \"localhost:22\">\nssh_tunnel = ngrok.connect(\"22\", \"tcp\")\n\n# Open a named tunnel from the config file\nnamed_tunnel = ngrok.connect(name=\"my-config-file-tunnel\")\n\n# Open an Internal Endpoint that's load balanced\n# <NgrokTunnel: \"https://some-endpoint.internal\" -> \"http://localhost:9000\">\ninternal_endpoint = ngrok.connect(addr=\"9000\",\n domain=\"some-endpoint.internal\",\n pooling_enabled=True)\n```\n\nThe [`connect`](https://pyngrok.readthedocs.io/en/latest/api.html#pyngrok.ngrok.connect) method takes `kwargs` as well,\nwhich allows\nyou to pass additional tunnel configurations that are supported by `ngrok` (or the `name` of a tunnel defined in\n`ngrok`'s config file), [as documented here](https://pyngrok.readthedocs.io/en/latest/#tunnel-configurations).\n\n### `ngrok`'s API\n\nThe [`api`](https://pyngrok.readthedocs.io/en/latest/api.html#pyngrok.ngrok.api) method allows you to use the local\n`ngrok` agent to make requests against [the `ngrok` API](https://ngrok.com/docs/agent/cli-api/), if you\nhave [set an API key](https://pyngrok.readthedocs.io/en/latest/#setting-the-authtoken-or-api-key).\nFor example, here's how you would reserve a `ngrok` domain, then create a Cloud Endpoint with an associated traffic\npolicy:\n\n```python\nfrom pyngrok import ngrok\n\ndomain = \"some-domain.ngrok.dev\"\nngrok.api(\"reserved-domains\", \"create\",\n \"--domain\", domain)\nngrok.api(\"endpoints\", \"create\",\n \"--bindings\", \"public\",\n \"--url\", f\"https://{domain}\",\n \"--traffic-policy-file\", \"policy.yml\")\n```\n\n### Command Line Usage\n\nThis package puts the default `ngrok` binary on your path, so all features of `ngrok` are\navailable on the command line.\n\n```sh\nngrok http 80\n```\n\nFor details on how to fully leverage `ngrok` from the command line,\nsee [`ngrok`'s official documentation](https://ngrok.com/docs/agent/cli/).\n\n## Documentation\n\nFor more advanced usage, `pyngrok`'s official documentation is available\non [Read the Docs](https://pyngrok.readthedocs.io).\n\n### Integration Examples\n\n- [Flask](https://pyngrok.readthedocs.io/en/latest/integrations.html#flask)\n- [Django](https://pyngrok.readthedocs.io/en/latest/integrations.html#django)\n- [Docker](https://pyngrok.readthedocs.io/en/latest/integrations.html#docker)\n- [Google Colab](https://pyngrok.readthedocs.io/en/latest/integrations.html#google-colaboratory)\n- [End-to-End Testing](https://pyngrok.readthedocs.io/en/latest/integrations.html#end-to-end-testing)\n\n## Contributing\n\nIf you would like to get involved, be sure to review\nthe [Contribution Guide](https://github.com/alexdlaird/pyngrok/blob/main/CONTRIBUTING.rst).\n\nWant to contribute financially? If you've found `pyngrok` useful, [sponsorship](https://github.com/sponsors/alexdlaird)\nwould also be greatly appreciated!\n",
"bugtrack_url": null,
"license": "MIT License\n \n Copyright (c) 2018-2025 Alex Laird\n \n Permission is hereby granted, free of charge, to any person obtaining a copy\n of this software and associated documentation files (the \"Software\"), to deal\n in the Software without restriction, including without limitation the rights\n to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n copies of the Software, and to permit persons to whom the Software is\n furnished to do so, subject to the following conditions:\n \n The above copyright notice and this permission notice shall be included in all\n copies or substantial portions of the Software.\n \n THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n SOFTWARE.\n ",
"summary": "A Python wrapper for ngrok",
"version": "7.2.12",
"project_urls": {
"Changelog": "https://github.com/alexdlaird/pyngrok/blob/main/CHANGELOG.md",
"Documentation": "https://pyngrok.readthedocs.io",
"Source Code": "https://github.com/alexdlaird/pyngrok",
"Sponsor": "https://github.com/sponsors/alexdlaird"
},
"split_keywords": [
"tunnel",
" webhook",
" reverse-proxy",
" ngrok",
" localhost",
" localtunnel",
" ingress",
" tunneling"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "7b81121c612fed8c247e7703cfcc5c3a04389a575e95bacbc316c0d371eb6757",
"md5": "a85550222222ce24630f6792c1938eb2",
"sha256": "a32c3146214e5a693b809e7cea705e29343050fee7047195f50244f4b8ba11e3"
},
"downloads": -1,
"filename": "pyngrok-7.2.12-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a85550222222ce24630f6792c1938eb2",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 26049,
"upload_time": "2025-07-09T19:17:53",
"upload_time_iso_8601": "2025-07-09T19:17:53.145901Z",
"url": "https://files.pythonhosted.org/packages/7b/81/121c612fed8c247e7703cfcc5c3a04389a575e95bacbc316c0d371eb6757/pyngrok-7.2.12-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "647a6f96513de7cadd81858b4e2bb8a31052b552cb21baeec305a5d0cac94a25",
"md5": "c1a8c6d88c828208e3b45fe293438aa9",
"sha256": "1cce4d785619b8064bca7e6f6c8a3454d69aaa5fcff0f35bd05aa81254ce12ff"
},
"downloads": -1,
"filename": "pyngrok-7.2.12.tar.gz",
"has_sig": false,
"md5_digest": "c1a8c6d88c828208e3b45fe293438aa9",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 45075,
"upload_time": "2025-07-09T19:17:54",
"upload_time_iso_8601": "2025-07-09T19:17:54.391743Z",
"url": "https://files.pythonhosted.org/packages/64/7a/6f96513de7cadd81858b4e2bb8a31052b552cb21baeec305a5d0cac94a25/pyngrok-7.2.12.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-09 19:17:54",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "alexdlaird",
"github_project": "pyngrok",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "pyngrok"
}
