pyngrok Documentation

You can use pre-built images from alexdlaird/pyngrok on Docker Hub.

• Interactive Python shell: docker run -e NGROK_AUTHTOKEN=$NGROK_AUTHTOKEN -it alexdlaird/pyngrok
• Interactive Bash shell: docker run -e NGROK_AUTHTOKEN=$NGROK_AUTHTOKEN -it alexdlaird/pyngrok /bin/bash
• Custom Config: Mount your local ngrok.yml to /root/.config/ngrok/ngrok.yml using a volume.
• Web Inspector: To access the ngrok web inspector, expose port 4040 and ensure your config sets web_addr: 0.0.0.0:4040.

# Run interactive bash
docker run -e NGROK_AUTHTOKEN=$NGROK_AUTHTOKEN -it alexdlaird/pyngrok /bin/bash

# Run with custom config
docker run -v ./ngrok.yml:/root/.config/ngrok/ngrok.yml -it alexdlaird/pyngrok

# Expose Web Inspector
docker run --env-file .env -p 4040:4040 -it alexdlaird/pyngrok

For Django, add a USE_NGROK flag to your settings.py that checks os.environ.get("RUN_MAIN", None) != "true". To trigger the tunnel creation when the development server starts, extend AppConfig.ready() in one of your apps.py files. Inside ready(), use ngrok.connect(port) to open the tunnel, then update settings.BASE_URL with the resulting public_url so that your application's internal logic (like webhooks) uses the public endpoint.

# In settings.py
USE_NGROK = os.environ.get("USE_NGROK", "False") == "True" and os.environ.get("RUN_MAIN", None) != "true"

# In apps.py
class CommonConfig(AppConfig):
    def ready(self):
        if settings.USE_NGROK:
            from pyngrok import ngrok
            # Logic to determine port from sys.argv...
            public_url = ngrok.connect(port).public_url
            settings.BASE_URL = public_url

To develop AWS Lambda functions locally, use a Flask application as a shim. Create a Flask Blueprint that captures incoming requests and transforms them into the event dictionary format expected by your Lambda handler. You can then use pyngrok to expose this Flask shim, allowing you to test your Lambda logic via public HTTP requests.

from flask import Blueprint, request
import json
from lambdas.foo_GET import lambda_function as foo_GET

bp = Blueprint("lambda_routes", __name__)

@bp.route("/foo")
def route_foo():
    # Transform Flask request into Lambda event
    event = {
        "someQueryParam": request.args.get("someQueryParam")
    }
    return json.dumps(foo_GET.lambda_handler(event, {}))

To debug common issues, configure the standard Python logging module to stream DEBUG level logs to the console. This will surface the root cause of failures during pyngrok method calls.

import logging
from pyngrok import ngrok

# Setup a logger
logger = logging.getLogger()
logger.setLevel(logging.DEBUG)
handler = logging.StreamHandler()
handler.setFormatter(logging.Formatter("%(asctime)s - %(name)s - %(levelname)s - %(message)s"))
logger.addHandler(handler)

# Call the pyngrok method throwing the error
ngrok.connect()

In FastAPI, use a BaseSettings class (e.g., via Pydantic) to manage USE_NGROK and BASE_URL. When the application initializes, if USE_NGROK is enabled, import ngrok, connect to the local port (defaulting to 8000 or parsed from --port), and update your settings object with the public_url returned by the tunnel.

from fastapi import FastAPI
from pydantic import BaseSettings
from pyngrok import ngrok

class Settings(BaseSettings):
    BASE_URL = "http://localhost:8000"
    USE_NGROK = os.environ.get("USE_NGROK", "False") == "True"

settings = Settings()
app = FastAPI()

if settings.USE_NGROK:
    port = sys.argv[sys.argv.index("--port") + 1] if "--port" in sys.argv else "8000"
    public_url = ngrok.connect(port).public_url
    settings.BASE_URL = public_url

You can install pyngrok using pip or conda. Once installed, pyngrok is available as a Python package, and the ngrok binary is added to your command line path.

# Using pip
pip install pyngrok

# Using conda
conda install -c conda-forge pyngrok

Since pyngrok is a wrapper, errors are often caused by the underlying ngrok binary. To ensure pyngrok is managing the correct version of ngrok, run ngrok in your terminal. The output must end with PYNGROK VERSION: |pyngrok_version|.

If you see a different version or no PYNGROK VERSION string, another ngrok installation (e.g., via Homebrew or npm) is likely higher in your $PATH. You should reorder your $PATH to prioritize the pyngrok managed binary.

To further isolate if the issue is with ngrok or your Python code, try running these commands:

1. Headless mode: ngrok start --none --log stdout
2. Simple HTTP tunnel: ngrok http 80 --log stdout

If these commands work in the terminal but your Python code fails, the issue is likely in your application's configuration.