{"id":6009,"library":"ngrok","title":"ngrok Python SDK","description":"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.","status":"active","version":"1.7.0","language":"en","source_language":"en","source_url":"https://github.com/ngrok/ngrok-python","tags":["networking","tunneling","ingress","development","api"],"install":[{"cmd":"pip install ngrok","lang":"bash","label":"Install ngrok Python SDK"}],"dependencies":[],"imports":[{"symbol":"ngrok","correct":"import ngrok"}],"quickstart":{"code":"import ngrok\nimport os\nimport time\n\n# Ensure NGROK_AUTHTOKEN is set in your environment variables\n# or pass it directly: ngrok.forward(9000, authtoken=\"YOUR_AUTHTOKEN\")\n\nif os.environ.get('NGROK_AUTHTOKEN') == None:\n    print(\"WARNING: NGROK_AUTHTOKEN environment variable not set. Please set it for ngrok to function correctly.\")\n\n# Establish connectivity to a local service running on port 9000\n# For this example, imagine a simple HTTP server is running on localhost:9000\nlistener = ngrok.forward(9000, authtoken_from_env=True)\n\nprint(f\"ngrok Ingress established at {listener.url()}\")\n\n# Keep the listener alive\ntry:\n    while True:\n        time.sleep(1)\nexcept KeyboardInterrupt:\n    print(\"\\nClosing ngrok listener\")\n    ngrok.disconnect(listener.url())\n    ngrok.kill()","lang":"python","description":"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."},"warnings":[{"fix":"For direct application ingress, use `pip install ngrok` and `import ngrok`. For managing the ngrok binary, use `pip install pyngrok` and `import pyngrok`.","message":"There 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.","severity":"gotcha","affected_versions":"All versions"},{"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')`.","message":"An 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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"For 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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-14T00:00:00.000Z","next_check":"2026-07-13T00:00:00.000Z"}