{"id":3762,"library":"pyngrok","title":"pyngrok","description":"pyngrok is a Python wrapper for ngrok, a reverse proxy tool that opens secure tunnels from public URLs to localhost. It manages its own ngrok binary, making the ngrok client available via a convenient Python API and the command line. This allows for rapid development, testing webhooks, and exposing local services. The current version is 8.0.0, and the library is actively maintained.","status":"active","version":"8.0.0","language":"en","source_language":"en","source_url":"https://github.com/alexdlaird/pyngrok","tags":["ngrok","tunneling","reverse proxy","development","webhook","localhost"],"install":[{"cmd":"pip install pyngrok","lang":"bash","label":"Install pyngrok"}],"dependencies":[{"reason":"pyngrok is a wrapper around the ngrok command-line tool. It manages the download and installation of the ngrok binary.","package":"ngrok binary","optional":false}],"imports":[{"note":"The primary interface is directly accessible via `from pyngrok import ngrok`.","wrong":"import pyngrok.ngrok","symbol":"ngrok","correct":"from pyngrok import ngrok"},{"note":"Used for global configuration settings like `auth_token` or `ngrok_path`.","symbol":"conf","correct":"from pyngrok import conf"}],"quickstart":{"code":"import os\nfrom pyngrok import ngrok, conf\n\n# Get your ngrok authtoken from the environment or replace with your actual token.\n# You can obtain one from https://ngrok.com/signup\nNGROK_AUTH_TOKEN = os.environ.get(\"NGROK_AUTHTOKEN\", \"YOUR_NGROK_AUTHTOKEN\")\n\nif NGROK_AUTH_TOKEN == \"YOUR_NGROK_AUTHTOKEN\":\n    print(\"WARNING: Please set the NGROK_AUTHTOKEN environment variable or replace 'YOUR_NGROK_AUTHTOKEN' in the code.\")\n    print(\"         Some ngrok features may be limited without an authtoken.\")\n    # Attempt to set the authtoken anyway, it might work for basic free-tier tunnels\n    conf.get_default().auth_token = NGROK_AUTH_TOKEN\nelse:\n    ngrok.set_auth_token(NGROK_AUTH_TOKEN)\n\ntry:\n    # Open an HTTP tunnel to a local service running on port 8000\n    # Ensure a service is running on this port before connecting.\n    http_tunnel = ngrok.connect(8000)\n    print(f\"ngrok tunnel is live: {http_tunnel.public_url}\")\n\n    # The tunnel will remain open until `ngrok.kill()` is called or the script exits.\n    input(\"Press Enter to close the tunnel and exit...\")\n\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")\nfinally:\n    # Disconnect any active ngrok tunnels and kill the ngrok process\n    ngrok.kill()\n    print(\"ngrok tunnel closed.\")\n","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"All versions, especially major upgrades"},{"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`.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure your local web server, API, or service is fully started and listening on the specified port *before* `ngrok.connect()` is called.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}