Elastic Transport for Python provides transport classes and utilities shared among various Python Elastic client libraries. It serves as a low-level HTTP client, powering the official Elasticsearch Python client and other Elastic projects. The library is currently at version 9.2.1 and follows a release cadence aligned with the major and minor versions of the Elastic Stack, with patch numbers incremented for bug fixes within a minor release.
Install & Compatibility
Where this runs
tested against v9.4.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.9100 runs
installs and imports cleanly · install 0.0s · import 0.470s · 19.5MB
glibcpy 3.10–3.9100 runs
installs and imports cleanly · install 1.8s · import 0.410s · 20MB
18MB installed
● package 18MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Transport
✓ from elastic_transport import Transport
The core class for managing nodes and performing HTTP requests.
RequestsHttpNode
✓ from elastic_transport import RequestsHttpNode
To use 'requests' as the underlying HTTP client.
AiohttpHttpNode
✓ from elastic_transport import AiohttpHttpNode
To use 'aiohttp' as the underlying asynchronous HTTP client.
HttpxHttpNode
✓ from elastic_transport import HttpxHttpNode
To use 'httpx' as the underlying synchronous HTTP client.
HttpxAsyncHttpNode
✓ from elastic_transport import HttpxAsyncHttpNode
To use 'httpx' as the underlying asynchronous HTTP client.
ApiError
✓ from elastic_transport import ApiError
For handling API-specific errors, introduced in version 8.x.
TransportError
✓ from elastic_transport import TransportError
For handling transport-level errors (e.g., connection issues).
This quickstart demonstrates how to initialize the `Transport` class, either connecting to a local Elasticsearch instance or an Elastic Cloud deployment using environment variables. It then performs a basic GET request to the cluster root and prints connection details. The `transport.close()` method should be called to close HTTP connections when the transport is no longer needed.
import os
from elastic_transport import Transport, NodeConfig
# Configure nodes - replace with your Elasticsearch host(s)
# For local testing, default to 'http://localhost:9200'
# For cloud, use CLOUD_ID and API_KEY environment variables
cloud_id = os.environ.get('ELASTIC_CLOUD_ID', '')
api_key = os.environ.get('ELASTIC_API_KEY', '')
node_configs = [
NodeConfig("http://localhost:9200")
]
if cloud_id and api_key:
# Use Cloud ID and API Key for Elastic Cloud
transport = Transport(
node_configs=[], # node_configs are derived from cloud_id
cloud_id=cloud_id,
api_key=(api_key,)
)
else:
transport = Transport(node_configs=node_configs)
try:
# Perform a GET request to the root ('/') which often returns cluster info
# The response is a tuple of (ApiResponseMeta, deserialized_body)
meta, body = transport.perform_request("GET", "/")
print("Successfully connected to Elasticsearch!")
print(f"Cluster Name: {body.get('cluster_name')}")
print(f"Status Code: {meta.status}")
except Exception as e:
print(f"Failed to connect or perform request: {e}")
print("Ensure Elasticsearch is running and accessible at the specified host(s)")
print("Or check your ELASTIC_CLOUD_ID and ELASTIC_API_KEY environment variables.")
transport.close()
Debug
Known issues
breakingPython 3.8 and 3.9 support was removed in version 9.2.0. Python 3.7 support was dropped in 8.15.0.fixUpgrade to Python 3.10 or newer.
affects: >=8.15.0, >=9.2.0
breakingThe exception hierarchy changed significantly in version 8.x. `TransportError` now only covers transport-level errors (e.g., connection timeouts), while `ApiError` must be used for API-specific errors (e.g., index not found).fixUpdate exception handling logic to catch `ApiError` for errors originating from the Elasticsearch API.
affects: >=8.0.0
gotchaWhen using `HttpxAsyncHttpNode`, 404 responses no longer raise exceptions by default; instead, the response with status 404 is returned. This changes the expected error handling behavior for 'not found' scenarios.fixExplicitly check the `meta.status` (HTTP status code) of the response for 404s if you need to treat them as errors.
affects: >=8.15.0
gotchaEnsure compatibility with `httpx` by installing `httpx v0.28.0+` if using the `httpx` backend. Older versions may cause compatibility issues.fixUpgrade your `httpx` dependency to `v0.28.0` or higher if you use `elastic-transport[httpx]`.
affects: >=8.17.1
gotchaThe `urllib3` library is the default HTTP client backend. To use `requests`, `aiohttp`, or `httpx`, you must install the respective extra dependencies (e.g., `elastic-transport[requests]`) and explicitly pass the corresponding `NodeConfig` or `node_class` to the `Transport` constructor.fixInstall the desired HTTP client extra and configure the `Transport` accordingly, e.g., `Transport(node_configs=[NodeConfig('...', http_compress=True)], node_class=RequestsHttpNode)`. affects: *
breakingThe NodeConfig constructor signature changed from accepting a full URL string to requiring separate 'scheme', 'host', and 'port' arguments.fixInstantiate NodeConfig with explicit keyword arguments for scheme, host, and port, e.g., `NodeConfig(scheme='http', host='localhost', port=9200)`.
affects: >=8.0.0
breakingThe NodeConfig constructor expects separate 'host' and 'port' arguments, not a single URL string. Passing a full URL string as the first argument will result in a TypeError.fixInitialize NodeConfig with separate 'host' and 'port' arguments, for example, use NodeConfig('localhost', 9200, scheme='http') for the URL 'http://localhost:9200'. affects: >=7.0.0
Errors
Common errors & fixes
elastic_transport.ConnectionError: Connection error caused by: ConnectionError('Connection refused')
This error indicates that the Python client could not establish a connection with the Elasticsearch server, often because the server is not running, is inaccessible due to a firewall, or the host/port configuration is incorrect.
fixEnsure the Elasticsearch service is running, verify the host and port in your client configuration match the Elasticsearch server's settings (default HTTP port is 9200), and check for any firewall rules blocking the connection. For Docker environments, ensure containers can communicate using service names instead of 'localhost'.
elastic_transport.TransportError: Transport error
This is a generic exception from the 'elastic-transport' package, signaling a problem that occurred before an HTTP response was received. It can be caused by various underlying issues, including network connectivity problems, an unresponsive Elasticsearch server, or an invalid request body.
fixExamine the full traceback and associated messages for more specific clues. Common resolutions include checking network stability, ensuring the Elasticsearch server is healthy and not overloaded, verifying that request bodies are not empty or malformed, and inspecting Elasticsearch logs for server-side errors.
ModuleNotFoundError: No module named 'elastic_transport'
This error means the Python interpreter cannot find the 'elastic_transport' package, usually because it has not been installed, or the current Python environment differs from where the package was installed.
fixInstall the package using pip: `python -m pip install elastic-transport`. If already installed, ensure you are running your script within the correct Python virtual environment where `elastic-transport` was installed.
elastic_transport.TlsError: TLS error caused by: SSLError([SSL: WRONG_VERSION_NUMBER] wrong version number)
This error typically occurs when the client attempts to connect using the wrong protocol (e.g., HTTPS client trying to connect to an HTTP server, or vice-versa) or there's a mismatch in SSL/TLS versions or certificates.
fixVerify that the `scheme` in your client configuration ('http' or 'https') matches the Elasticsearch server's configuration. If using HTTPS, ensure the server's SSL certificate is correctly configured and trusted by the client, and that the TLS versions are compatible. Audit
Dependencies
pythonrequiredRequires Python 3.10 or newer.
urllib3requiredDefault HTTP client backend.
requestsoptionalOptional HTTP client backend (RequestsHttpNode).
aiohttpoptionalOptional asynchronous HTTP client backend (AiohttpHttpNode).
httpxoptionalOptional asynchronous HTTP client backend (HttpxHttpNode, HttpxAsyncHttpNode).