---
id: ngrok
version: "1.7.0"
license: MIT OR Apache-2.0
license_treatment: permissive
maintenance: active
---

# ngrok — The ngrok Agent SDK for Python

License: permissive · Maintenance: active · Downloads: 334.5K/mo

## What it is and what it does

ngrok-python is the official Python SDK for ngrok, a globally distributed gateway that creates secure public connectivity to applications running locally or in any environment. It requires no external binaries—the SDK is self-contained in compiled wheels for macOS, Linux, Windows, and ARM platforms. You use it by importing ngrok, calling forward() to create a listener on a local port or address, and receiving a public URL that routes traffic to your service. The SDK handles authentication via an authtoken (obtained free from ngrok.com), supports HTTP and TCP listeners with optional TLS, basic auth, OAuth, and other middleware options, and provides builder classes for more advanced session and listener control.

The package is production-stable (Development Status 5), actively maintained with recent releases, and carries no known security vulnerabilities. It has no runtime dependencies beyond Python itself, so installation is straightforward once the platform-specific wheel downloads. It's designed for developers who need quick, secure ingress to local services—useful for webhooks, local development testing, CI/CD integrations, and exposing services behind firewalls.

Use it for:

- Expose a local webhook receiver to the internet for testing third-party integrations without deploying.
- Create a public URL for a development server to share with teammates or external services for real-time testing.
- Tunnel a local database or API endpoint through ngrok for secure remote access during development.
- Set up CI/CD pipeline callbacks that need to reach a local service running on a developer's machine.
- Forward TCP traffic to a game server or application running on localhost for remote players to connect.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Exposes ngrok's secure gateway service to Python applications, enabling you to create public-facing listeners for local services without binaries or external processes.

Yes. The package is production-stable, actively maintained, has no security vulnerabilities, and solves a real problem (secure local-to-public connectivity) with zero runtime dependencies. The only gotcha is the medium install friction from platform-specific wheels and the hard requirement for Python >= 3.12 and a free ngrok authtoken. If you need ingress to a local service, this is the official, straightforward way to do it.

## Install

pip install ngrok
uv add ngrok
poetry add ngrok

## Installing ngrok

Before you install: Medium install friction due to compiled wheels across multiple platforms (macOS, Linux, Windows, ARM architectures). Actively maintained with recent releases; no runtime dependencies to manage.

License in practice: Dual-licensed under MIT or Apache-2.0, both permissive. You may use, modify, and distribute freely under either license's terms.

Quickstart:

pip install ngrok

import ngrok
import time

listener = ngrok.forward(9000, authtoken_from_env=True)
print(f"Ingress established at {listener.url()}")
try:
    while True:
        time.sleep(1)
except KeyboardInterrupt:
    print("Closing listener")

Requires NGROK_AUTHTOKEN environment variable set with a valid token from ngrok.com dashboard, and Python >= 3.12.

Verify before relying:

- Whether the SDK works with async/await patterns beyond the builder example shown in the description.
- Performance characteristics and throughput limits for different listener types (HTTP, TCP, TLS).
- Whether Unix socket support is available on all supported platforms.

## Package facts

- License: MIT OR Apache-2.0 (permissive)
- Python support: supports_current
- Install friction: medium
- Maintenance: active
- Downloads: 334.5K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

ngrok python sdk, expose local service publicly, secure tunneling gateway, localhost to internet, ingress connectivity python, public url for local app, reverse proxy tunneling, tunneling, ingress, local-development

[View on SkillFed](https://skillfed.io/packages/ngrok) · [View on PyPI](https://pypi.org/project/ngrok/)