NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
PyPI · #3996 most downloaded on PyPI
A Python wrapper for ngrok
Last release 5 months ago
29 Apr 2026
Release timing varies
gaps range from 8 days to 4 months
Nearly every release is documented
notes for 55 of the last 60 stable releases
Nothing withdrawn
no release was ever pulled
8 years old
113 releases · first in 2018
Build and stability improvements.
Build and stability improvements.
Full support for ngrok 's v3 config schema. Set PyngrokConfig.config_version="3" to have ngrok.connect() and other methods use ngrok 's Endpoints inst
One column per quarter.
ngrok's v3 config schema. Set PyngrokConfig.config_version="3" to have ngrok.connect() and other methods use ngrok's Endpoints instead of Tunnels.NgrokTunnel.upstream attribute, populated from the v3 endpoint response (or synthesized from config.addr for v2). Raw v3 fields like traffic_policy and bindings remain accessible via NgrokTunnel.data.addr / proto args are interpolated to a v3 upstream block when config_version="3" is set.ngrok_version parameter default from "v3" to "3". A leading "v" is stripped where this value is consumed, so "v3" continues to be accepted.Removed support for ngrok v2, as v2 binaries are no longer distributed by ngrok . Only ngrok v3 is now supported.
ngrok v2, as v2 binaries are no longer distributed by ngrok. Only ngrok v3 is now supported..zip to .tgz..tgz archive extraction support alongside existing .zip support.Migrated CDN URLs from bin.equinox.io to bin.ngrok.com .
bin.equinox.io to bin.ngrok.com.Removed support for ngrok Edges, as they are deprecated by ngrok and will be sunset December 31st, 2025. See this issue for more details.
ngrok Edges, as they are deprecated by ngrok and will be sunset December 31st, 2025. See this issue for more details.Added Support for XDG_CONFIG_HOME .
XDG_CONFIG_HOME.As of ngrok Agent 3.29.0 , two tunnels cannot have the same name (and this includes tunnel's defined in the config, even if they are not started). As
ngrok Agent 3.29.0, two tunnels cannot have the same name (and this includes tunnel's defined in the config, even if they are not started). As such, when name is given and matches a tunnel defined in the config, pyngrok will append "-api" to the tunnel's name when starting it.Removed Support for Python 3.8.
Support for s390x , ppc64 , and ppc64le architectures.
s390x, ppc64, and ppc64le architectures.Build and stability improvements.
Nothing published for this version
Support for MSYS2's `mingw` when installing the agent. Like cygwin, it is mapped to its corresponding Windows binary.
mingw when installing the agent. Like cygwin, it is mapped to its corresponding Windows binary.cygwin from dict of PLATFORMS, since the installer can just map to its corresponding Windows CDN value instead.`ngrok.api()`, allowing api commands to be executed from the agent.
ngrok.api(), allowing api commands to be executed from the agent.stderr is now sent to stdout in capture_run_process().
stderr is now sent to stdout in capture_run_process().Nothing published for this version
Deprecation warning when using Labeled Tunnels, since ngrok Edges will be sunset December 31st, 2025. See this issue for more details.
ngrok Edges will be sunset December 31st, 2025. See this issue for more details.Behavior where ngrok default config file is always installed to conf.DEFAULT_NGROK_CONFIG_PATH, even when override PyngrokConfig.config_path is given.
ngrok default config file is always installed to conf.DEFAULT_NGROK_CONFIG_PATH, even when override PyngrokConfig.config_path is given. This contradicted documentation, and is inconsistent with parallel behavior in java-ngrok.Support for ngrok config version 3.
ngrok config version 3.ngrok config file.PyngrokConfig.api_key, it will attempt to use the environment variable NGROK_API_KEY if it is set.Permission for installed binary to limit execute to user.
Include SSL handshake failures in installer retry logic.
ngrok's documentation.Build and stability improvements.
conf.DEFAULT_NGROK_PATH defaults to installing the binary alongside ngrok's configs rather than alongside the
code (putting the binary in the venv can cause odd behavior, or security concerns).Build and stability improvements.
### Added - obj parsing in `NgrokLog`. - raises to documentation. - Build improvements.
obj parsing in NgrokLog.raises to documentation.conf.VERSION, moved all version information to pyngrok/__init__.py. Get package version with from pyngrok import __version__ instead.
conf.VERSION, moved all version information to pyngrok/__init__.py. Get package version
with from pyngrok import __version__ instead.Renamed make check-style to make check.
make check-style to make check.Relative dependency pinning in pyproject.toml.
pyproject.toml.flake8 with make check-style).requirements.txt files to streamline in to pyproject.toml.Fix for instability from an ngrok binary change.
pyproject.toml.ngrok binary change.Support for 3.6 and 3.7. To use pyngrok with Python 3.7 or lower, pin pyngrok<7.1.
pyngrok with Python 3.7 or lower, pin pyngrok<7.1.Test improvements, suite now respects NGROK_AUTHTOKEN for all necessary tests (skipped if not set, rather than tests failing).
NGROK_AUTHTOKEN for all necessary tests (skipped if not set, rather than tests
failing).If a value for PyngrokConfig.auth_token is not set, it will attempt to use the environment variable NGROK_AUTHTOKEN if it is set.
PyngrokConfig.auth_token is not set, it will attempt to use the environment variable NGROK_AUTHTOKEN if it is
set.Build improvements, including wheel support.
wheel support.pyngrok to no longer install the config file in a legacy location, now respects `ngrok`'s default locations.
pyngrok to no longer install the config file in a legacy location, now
respects ngrok's default locations.### Added - Documentation improvements.
Moved `NgrokLog` from pyngrok.process to pyngrok.log.
NgrokLog from pyngrok.process
to pyngrok.log.pyngrok with Python 3.5, pin pyngrok<7.### Added - Documentation improvements. ### Fixed - Minor bugs.
Nothing published for this version
Support for labels, so `ngrok`'s Labeled Tunnel Configuration is now supported, which enables basic support for `ngrok`'s Edge.
labels,
so ngrok's Labeled Tunnel Configuration
is now supported, which enables basic support for ngrok's Edge.api_key to PyngrokConfig, which can be set so pyngrok can interface with Edges when using labels.auth
param, so it can now be used to pass the Bearer token to ngrok's API.id to NgrokTunnel.Default installer behavior to download ngrok v3 by default.
ngrok v3 by default.Support for basic_auth parameter in ngrok v3.
basic_auth parameter in ngrok v3.### Fixed - Documentation improvements. - Test improvements.
Support for Python 3.10 and 3.11.
Support for `ngrok` v3 (v2 is still used by default).
ngrok v3 (v2 is still used by default).pyngrok with ngrok v3.reconnect_session_retries from PyngrokConfig, instead relying on ngrok's own built-in retry mechanism on startup fails.
reconnect_session_retries from PyngrokConfig, instead relying on ngrok's own built-in retry mechanism on startup
fails.Darwin 64-bit ARM support, as this was added to ngrok itself.
ngrok itself.ngrok itself.reconnect_session_retries is a new configuration parameter in PyngrokConfig, which determines the max number of times to retry establishing a new sess
reconnect_session_retries is a new configuration parameter in PyngrokConfig, which determines the max number of
times to retry establishing a new session with ngrok if the connection fails on startup.### Fixed - Build improvements.
### Fixed - Build improvements. - Test improvements.
Migrated build from Travis CI to GitHub Actions.
bind_tls was set to False.### Added - Documentation improvements. ### Fixed - Build improvements.
Support for `ngrok`'s tunnel definitions when calling ngrok.connect(). If a tunnel definition in ngrok's config matches the given name, it will be use
ngrok's tunnel definitions
when calling ngrok.connect(). If a tunnel
definition in ngrok's config matches the given name, it will be used to start the tunnel.ngrok tunnel definition
named "pyngrok-default" when
calling ngrok.connect(). When name
is None and a "pyngrok-default" tunnel definition exists it ngrok's config, it will be used.ngrok is already running without also implicitly starting it.ngrok
and pyngrok versions in a tuple.conf.DEFAULT_PYNGROK_CONFIG.conf.DEFAULT_PYNGROK_CONFIG.refresh_metrics()
to NgrokTunnel.data to NgrokTunnel, which holds the
original tunnel data.ngrok, if an
update is available.str of the
public URL. The returned NgrokTunnel has a reference to the previously returned public_url in it.port (the first arg) to addr to match ngrok's documentation.options kwarg should now be unpacked, pass each option directly to the method as a kwarg.__init__()'s
params (data, pyngrok_config, and api_url) are now required.ngrok.disconnect() no longer installs and starts ngrok, it simply returns if the ngrok process has not been
started.conf.DEFAULT_PYNGROK_CONFIG to conf._default_pyngrok_config (
use conf.set_default() instead).ngrok.ensure_ngrok_installed() to ngrok.install_ngrok().ngrok.install_ngrok() (formerly ngrok.ensure_ngrok_installed()) changed its signature, now takes
a pyngrok_config (optional) instead of ngrok_path as its only arg.process._ensure_path_ready() to process._validate_path().return_ngrok_tunnel from ngrok.connect(). The kwarg can still be passed, but it will do nothing, it now always
uses the True behavior.The next release, 5.0.0, contains breaking changes, including dropping support for Python 2.7. 4.2.x is meant to ease migration between 4.1.x and 5.0.…
The next release, 5.0.0, contains breaking changes, including dropping support for Python 2.7. 4.2.x is meant to ease
migration between 4.1.x and 5.0.0 and should not be pinned, as it will not be supported after 5.0.0 is released. To
prepare for these breaking changes, see the changelog below. To avoid these breaking changes altogether, or if
Python 2.7 support is still needed, pin pyngrok~=4.1.0.
options
with kwargs, maintained backwards compatibility. Support for passing options as a dict will be removed in 5.0.0,
unpack the dict as kwargs.return_ngrok_tunnel
to its args, which defaults to False for backwards compatibility. This will default to True in 5.0.0, and the flag
will be removed.conf.DEFAULT_PYNGROK_CONFIG, which will be removed in 5.0.0.Nothing published for this version
ngrok.get_version() to get ngrok and pyngrok versions in a tuple.
ngrok
and pyngrok versions in a tuple.refresh_metrics()
to NgrokTunnel.Nothing published for this version
An integration example for Google Colab.
An integration example for Google Colab.
ngrok.api_request() using params for filtering with special characters.params is now
properly documented as a dict instead of a list.ngrok logs.Validation for log_format in ngrok's config.yaml, as pyngrok depends on key/value logs.
log_format in ngrok's config.yaml, as pyngrok depends on key/value logs.log_level in ngrok's config.yaml, as pyngrok depends on the level being either info
or debug.### Fixed - Build improvements. - Documentation improvements.
When bind_tls is True, the public_url return from ngrok.connect() is now https.
bind_tls is True, the public_url return from ngrok.connect() is now https.The thread that monitors ngrok logs now maintains its own alive state instead of modifying PyngrokConfig.monitor_thread.
ngrok logs now maintains its own alive state instead of
modifying PyngrokConfig.monitor_thread.ngrok
logs is now daemonic, so it no longer
blocks the Python process from terminating.Your coding agent can read these notes before it upgrades. Set up the MCP server →