Install & Compatibility
Where this runs
tested against v2.5.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.95 runs
build_error
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 4.6s · import 0.722s · 66MB
65MB installed
● package 65MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
GlideClient
✓ from glide import GlideClient, NodeAddress
GlideClusterClient
✓ from glide import GlideClusterClient, NodeAddress
GlideClient (sync)
✓ from glide_sync import GlideClient, NodeAddress
For the synchronous client, import from `glide_sync`.
GlideClusterClient (sync)
✓ from glide_sync import GlideClusterClient, NodeAddress
For the synchronous cluster client, import from `glide_sync`.
This quickstart demonstrates connecting to a standalone Valkey instance and a Valkey cluster using `valkey-glide`'s asynchronous clients. It performs a `PING` command to verify connection and `SET`/`GET` operations. For cluster mode, ensure `VALKEY_CLUSTER_HOST` and `VALKEY_CLUSTER_PORT` environment variables are set to your cluster's entry point, or adjust the default `localhost:7000` to a running cluster node.
import asyncio
from glide import GlideClient, GlideClusterClient, NodeAddress
import os
async def main():
# Example for a standalone Valkey instance
# Ensure a Valkey server is running on localhost:6379 (e.g., via Docker)
# docker run -d --name valkey-server -p 6379:6379 valkey/valkey:latest
print("\n--- Standalone Client Example ---")
standalone_client = GlideClient([NodeAddress("localhost", 6379)])
try:
pong_response = await standalone_client.ping()
print(f"Standalone PING response: {pong_response}")
await standalone_client.set("mykey", "myvalue")
value = await standalone_client.get("mykey")
print(f"Standalone GET mykey: {value}")
except Exception as e:
print(f"Error with Standalone Client: {e}")
finally:
await standalone_client.close()
# Example for a Valkey cluster instance
# Replace with actual cluster addresses
# For local testing, you might need a local Valkey cluster setup
print("\n--- Cluster Client Example ---")
cluster_addresses = [NodeAddress(os.environ.get('VALKEY_CLUSTER_HOST', 'localhost'), int(os.environ.get('VALKEY_CLUSTER_PORT', '7000')))]
cluster_client = GlideClusterClient(cluster_addresses)
try:
cluster_pong_response = await cluster_client.ping()
print(f"Cluster PING response: {cluster_pong_response}")
await cluster_client.set("cluster_key", "cluster_value")
cluster_value = await cluster_client.get("cluster_key")
print(f"Cluster GET cluster_key: {cluster_value}")
except Exception as e:
print(f"Error with Cluster Client: {e}")
finally:
await cluster_client.close()
if __name__ == "__main__":
asyncio.run(main())
Debug
Known issues
gotchaOpenTelemetry can only be initialized once per process. Attempting to re-initialize it will not apply new configurations and requires a full application restart for changes to take effect.fixEnsure OpenTelemetry configuration is set up once at application startup. For changes, restart the application.
affects: All versions with OpenTelemetry support (2.0+)
gotchaConnecting to a TLS-enabled Valkey server without setting `use_tls=True` in the client configuration will result in connection timeouts.fixAlways explicitly set `use_tls=True` in `GlideClientConfiguration` or `GlideClusterClientConfiguration` when connecting to a TLS-enabled server. If using custom certificates, also provide the `root_certificates` parameter.
affects: All versions
gotchaCurrently, Alpine Linux / MUSL is NOT officially supported for the Python client. Users on these platforms may encounter compilation or runtime issues.fixUse a supported Linux distribution (e.g., Ubuntu, Amazon Linux) or macOS. Monitor official documentation for future Alpine/MUSL support.
affects: All versions 2.x.x
gotchaAutomatic compression/decompression in Valkey GLIDE is NOT compatible with Valkey commands that manipulate string data on the server side.fixAvoid using client-side compression for commands such as `APPEND`, `SETRANGE`, `GETRANGE`, etc., where the server needs to interpret or modify string data directly. Consult documentation for a full list of incompatible commands.
affects: All versions with compression support (Experimental)
gotchaThe synchronous Python client (from `glide_sync`) introduced in version 2.1 does not yet support all features available in the asynchronous client, specifically: Pub/Sub, Cluster scan, configuring an In-flight request limit, and OpenTelemetry integration.fixIf these features are required, use the asynchronous client (from `glide`). For synchronous workflows requiring these features, consider using an `asyncio` event loop to run asynchronous client calls.
affects: >=2.1.0
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'valkey_glide'
The Python module for Valkey GLIDE is named `glide`, not `valkey_glide`, and is installed via the `glide-py` package.
fixUse `import glide` or `from glide import GlideClient` after installing the package with `pip install glide-py`.
AttributeError: 'GlideClient' object has no attribute 'setex'
The `valkey-glide` client uses a unified `set` command with options for expiration and other functionalities, rather than separate commands like `SETEX` or `SETNX`.
fixUse the `set` command with `SetOptions.Expire` (for async) or `SetOptions.Expire(seconds=...)` (for sync) to set an expiration, e.g., `await client.set('key', 'value', options=[SetOptions.Expire(seconds=60)])`. TypeError: 'coroutine' object is not awaitable
An asynchronous method of `GlideClient` (e.g., `client.set()`) was called without the `await` keyword, or from a synchronous context.
fixEnsure that asynchronous `GlideClient` methods are called with `await` within an `async` function, or use the synchronous `GlideClient` if working in a synchronous execution flow.
GlideError: Failed to connect
The `valkey-glide` client failed to establish a connection to the Valkey server, often due to the server not running, incorrect host/port, or network/firewall issues.
fixVerify that the Valkey server is running, check the configured host and port (default is `localhost:6379`), and ensure no network or firewall rules are blocking the connection.
Upgrade
Version history
2.5.1latest on PyPI · released Aug 10, 2026
Audit
Dependencies
pythonrequiredRequired Python version.
anyiorequiredRequired for asynchronous operations.
protobufrequiredDependency listed on PyPI.
sniffiorequiredDependency listed on PyPI.
typing-extensionsrequiredDependency listed on PyPI.