pyngrok

Warnings

• breaking pyngrok version compatibility with ngrok binary. pyngrok 8.x aims to work with ngrok v3. If you have an older or conflicting ngrok binary on your system path, or if an older pyngrok (e.g., v7.x) installed ngrok v2, you might experience unexpected behavior or errors when trying to use v3-specific features.
  Fix: Ensure that `pyngrok` is managing its own `ngrok` binary by checking `ngrok`'s version (`ngrok -v` in terminal, looking for `PYNGROK VERSION`). If conflicts occur, reorder your `$PATH` or explicitly manage `ngrok`'s binary path via `pyngrok.conf.get_default().ngrok_path`. If upgrading, delete the old `ngrok` binary to force `pyngrok` to download the latest version.
• gotcha Ngrok Authtoken is crucial for advanced features. Without an authenticated ngrok agent, features like custom subdomains, reserved addresses, or increased tunnel durations are unavailable. Failing to set the `NGROK_AUTHTOKEN` can lead to `ngrok` launching with limitations.
  Fix: Obtain an authtoken from the ngrok dashboard and set it using `ngrok.set_auth_token("YOUR_AUTHTOKEN")` or by exporting it as an environment variable `NGROK_AUTHTOKEN`.
• gotcha PyngrokNgrokError on process startup. This error (e.g., 'The ngrok process was unable to start') often indicates an issue with the underlying ngrok binary's configuration or environment, not necessarily a bug in pyngrok.
  Fix: Debug by running the `ngrok` command directly from your terminal to see its output and error messages. Ensure no other processes are binding to the `ngrok`'s API port (default 4040). Check `ngrok`'s logs for more detailed error information. Ensure `ngrok` has necessary permissions to run.
• gotcha Tunnel connection refusal if no local service is running. If `ngrok.connect()` reports 'Failed to complete tunnel connection' or 'dial tcp 127.0.0.1:80: connect: connection refused', it means no service is actively listening on the target `localhost:port` specified.
  Fix: Ensure your local web server, API, or service is fully started and listening on the specified port *before* `ngrok.connect()` is called.

Install

• pip install pyngrok Install pyngrok

Imports

• ngrok

  from pyngrok import ngrok

  The primary interface is directly accessible via `from pyngrok import ngrok`.
• conf

  from pyngrok import conf

  Used for global configuration settings like `auth_token` or `ngrok_path`.

Quickstart

This quickstart demonstrates how to initialize pyngrok, set an ngrok authtoken (preferably via an environment variable), and open a basic HTTP tunnel to a local port. It then prints the public ngrok URL and waits for user input before gracefully closing the tunnel. An ngrok authtoken is highly recommended for full functionality and can be obtained from the ngrok dashboard.

import os
from pyngrok import ngrok, conf

# Get your ngrok authtoken from the environment or replace with your actual token.
# You can obtain one from https://ngrok.com/signup
NGROK_AUTH_TOKEN = os.environ.get("NGROK_AUTHTOKEN", "YOUR_NGROK_AUTHTOKEN")

if NGROK_AUTH_TOKEN == "YOUR_NGROK_AUTHTOKEN":
    print("WARNING: Please set the NGROK_AUTHTOKEN environment variable or replace 'YOUR_NGROK_AUTHTOKEN' in the code.")
    print("         Some ngrok features may be limited without an authtoken.")
    # Attempt to set the authtoken anyway, it might work for basic free-tier tunnels
    conf.get_default().auth_token = NGROK_AUTH_TOKEN
else:
    ngrok.set_auth_token(NGROK_AUTH_TOKEN)

try:
    # Open an HTTP tunnel to a local service running on port 8000
    # Ensure a service is running on this port before connecting.
    http_tunnel = ngrok.connect(8000)
    print(f"ngrok tunnel is live: {http_tunnel.public_url}")

    # The tunnel will remain open until `ngrok.kill()` is called or the script exits.
    input("Press Enter to close the tunnel and exit...")

except Exception as e:
    print(f"An error occurred: {e}")
finally:
    # Disconnect any active ngrok tunnels and kill the ngrok process
    ngrok.kill()
    print("ngrok tunnel closed.")