{"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":"python","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,"search_vec":"'8.0.0':57 'activ':62 'allow':43 'api':37 'avail':32 'binari':27 'client':31 'command':40 'conveni':35 'current':54 'develop':46,68 'expos':50 'librari':60 'line':41 'local':51 'localhost':21,70 'maintain':63 'make':28 'manag':23 'ngrok':8,26,30,64 'open':14 'proxi':11,67 'public':18 'pyngrok':1,2 'python':5,36 'rapid':45 'revers':10,66 'secur':15 'servic':52 'test':47 'tool':12 'tunnel':16,65 'url':19 'version':55 'via':33 'webhook':48,69 'wrapper':6","created_at":"2026-04-11T17:43:37.413666+00:00","updated_at":"2026-04-17T15:04:36.884361+00:00","problems":[{"fix":"Install pyngrok using pip: `pip install pyngrok`","cause":"The pyngrok library is not installed in your current Python environment.","error":"ModuleNotFoundError: No module named 'pyngrok'"},{"fix":"Check ngrok's logs for more details by enabling pyngrok logging (`logging.basicConfig(level=logging.DEBUG)`), ensure no other ngrok process is running, and verify your ngrok authtoken is correctly set using `ngrok.set_auth_token(\"YOUR_AUTHTOKEN\")` if needed. Running `ngrok start --none --log stdout` directly in the terminal can also help debug ngrok startup issues.","cause":"The underlying ngrok binary failed to start, often due to a configuration issue, missing dependencies, or an existing ngrok process occupying the API port (4040).","error":"pyngrok.exception.PyngrokNgrokError: The ngrok process was unable to start."},{"fix":"Ensure your local web service is fully started and listening on the exact port specified (e.g., `80`, `5000`) *before* calling `ngrok.connect()`. You might need to add a small delay or a retry mechanism in your code to wait for the local service to become available.","cause":"ngrok successfully created a public tunnel, but no local service (e.g., a web server, Flask app) is listening on the specified localhost port, or the service started after pyngrok tried to connect.","error":"Failed to complete tunnel connection. The connection to <public_sub>.ngrok.io was successfully tunneled to your ngrok client, but the client failed to establish a connection to the local address localhost:<port>. Make sure that a web service is running on localhost:<port> and that it is a valid address. The error encountered was: dial tcp 127.0.0.1:<port>: connect: connection refused."},{"fix":"For pyngrok 8.0.0, pass tunnel configurations directly as keyword arguments. Refer to the pyngrok documentation for the correct and supported keyword arguments for `ngrok.connect()` (e.g., `addr`, `proto`, `auth`, `subdomain`). Remove or correct the 'some_argument' keyword.","cause":"You are passing an unsupported or mistyped keyword argument to the `ngrok.connect()` method, or using syntax from an older pyngrok version that expected options in a dictionary format.","error":"TypeError: connect() got an unexpected keyword argument 'some_argument'"},{"fix":"Run `pyngrok.install_ngrok()` to download and install the ngrok binary, or ensure ngrok is installed and its path is accessible or configured correctly.","cause":"The ngrok executable is not found in the expected locations by pyngrok, often because it hasn't been downloaded or installed correctly.","error":"NgrokNgrokNotFound: ngrok binary not found!"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"8.1.2","cli_name":"ngrok","cli_version":"ngrok version 3.39.2","type":"library","homepage":"https://pyngrok.com","github":"https://github.com/alexdlaird/pyngrok","docs":"https://pyngrok.readthedocs.io","changelog":"https://github.com/alexdlaird/pyngrok/blob/main/CHANGELOG.md","pypi":"https://pypi.org/project/pyngrok/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["devops","http-networking","testing"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-29","next_check":"2026-07-28","install_tag":null}}