ngrok

library1.7.0pypypi✓ verified 84d ago

The ngrok Python SDK is an official, open-source library that enables developers to integrate secure ingress directly into their Python applications. It acts as a Python-packaged version of the ngrok Agent CLI, allowing applications to expose local services to the internet without complex network configurations. The library is actively maintained, with a current version of 1.7.0, and typically sees updates in line with major ngrok platform developments.

http-networking devops web-framework

pip install ngrok

github ↗package ↗homepage ↗changelog ↗

INSTALL

IMPORT

SIG · NGROK

ngrok

http-networkingpythonv1.7.0

Install

1.6s avg

Import

20ms

Disk

24MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.4.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.920 runs

installs and imports cleanly · install 0.0s · import 0.021s · 26MB

glibc

py 3.10–3.920 runs

installs and imports cleanly · install 1.6s · import 0.020s · 26MB

24MB installed

● package 24MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

ngrok

✓ import ngrok

This quickstart demonstrates how to expose a local service (assumed to be running on port 9000) to the internet using `ngrok.forward()`. It requires an ngrok authtoken, ideally set as an environment variable `NGROK_AUTHTOKEN`. The `while True: time.sleep(1)` loop keeps the tunnel active until a keyboard interrupt.

import ngrok import os import time # Ensure NGROK_AUTHTOKEN is set in your environment variables # or pass it directly: ngrok.forward(9000, authtoken="YOUR_AUTHTOKEN") if os.environ.get('NGROK_AUTHTOKEN') == None: print("WARNING: NGROK_AUTHTOKEN environment variable not set. Please set it for ngrok to function correctly.") # Establish connectivity to a local service running on port 9000 # For this example, imagine a simple HTTP server is running on localhost:9000 listener = ngrok.forward(9000, authtoken_from_env=True) print(f"ngrok Ingress established at {listener.url()}") # Keep the listener alive try: while True: time.sleep(1) except KeyboardInterrupt: print("\nClosing ngrok listener") ngrok.disconnect(listener.url()) ngrok.kill()

ngrok --version

Debug

Known issues

gotchaThere are multiple Python libraries related to ngrok. `ngrok` (ngrok-python) is the official SDK for embedding ngrok functionality directly into your application without needing a separate ngrok binary. `pyngrok` is a wrapper for the ngrok binary, managing its download and execution. `ngrok-api` is for interacting with the ngrok HTTP API. Ensure you are using the correct library for your use case.

fix

For direct application ingress, use `pip install ngrok` and `import ngrok`. For managing the ngrok binary, use `pip install pyngrok` and `import pyngrok`.

affects: All versions

gotchaAn ngrok authtoken is usually required for full functionality, especially for custom domains or advanced features. Failing to provide one will limit capabilities or prevent the tunnel from starting.

fix

Sign up on ngrok.com to get an authtoken. Set it as an environment variable `NGROK_AUTHTOKEN` or pass it directly to `ngrok.forward(..., authtoken='YOUR_AUTHTOKEN')`.

affects: All versions

gotchaFor long-running applications or when integrating with async frameworks, ensure the ngrok listener is properly managed to prevent resource leaks. The `ngrok.forward()` method may return an awaitable in async contexts.

fix

If not using a blocking call or an integrated framework, explicitly call `ngrok.disconnect()` for specific tunnels and `ngrok.kill()` to shut down the ngrok process when it's no longer needed, especially in serverless or containerized environments.

affects: All versions

Errors

Common errors & fixes

ERR_NGROK_3200

This error occurs when the ngrok agent is not online or the tunnel has been flagged by the automated moderation system.

fix

Ensure that your ngrok agent is running and connected. If the issue persists, check the ngrok documentation for ERR_NGROK_3200 or contact support.

ERR_NGROK_8012

This error indicates that traffic was successfully tunneled to the ngrok agent, but the agent failed to establish a connection to the upstream web service.

fix

Verify that your local service is running and accessible at the specified address. Ensure that the correct port is being used in the ngrok command.

PermissionError: [Errno 13] Permission denied: '/usr/local/lib/python3.11/dist-packages/pyngrok/bin/ngrok'

This error occurs when the user does not have the necessary permissions to install or run ngrok in the specified directory.

fix

Run the installation or command with elevated privileges using 'sudo', or install ngrok in a directory where you have write permissions.

The connection to https://<subdomain>.ngrok.io was successfully tunneled to your ngrok client, but the client failed to establish a connection to the local address 127.0.0.1:5000.

This error occurs when ngrok cannot connect to the local service at the specified address and port.

fix

Ensure that your local service is running on the specified port and is accessible. Verify that the port number in the ngrok command matches the port your service is using.

ModuleNotFoundError: No module named 'ngrok'

The ngrok Python SDK has not been installed in your current Python environment.

fix

Install the official ngrok Python SDK using pip: `pip install ngrok`

Upgrade

Version history

1.7.0latest on PyPI · released Dec 16, 2025

Audit

Dependencies

No dependency data recorded yet.

Agent activity

7 hits · last 30 days

node

Amazon

Resources

githubhttps://github.com/ngrok/ngrok-python ↗

packagehttps://pypi.org/project/ngrok/ ↗

homepagehttps://ngrok.com ↗

changeloghttps://github.com/ngrok/ngrok-python/blob/main/CHANGELOG.md ↗