Registry /
llm-agents / langgraph-checkpoint-redis
Install & Compatibility
Where this runs
tested against v0.5.2 · 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 11.3s · import 1.574s · 160MB
167MB installed
● package 167MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
RedisSaver
✓ from langgraph.checkpoint.redis import RedisSaver
AsyncRedisSaver
✓ from langgraph.checkpoint.redis.aio import AsyncRedisSaver
ShallowRedisSaver
✓ from langgraph.checkpoint.redis.shallow import ShallowRedisSaver
AsyncShallowRedisSaver
✓ from langgraph.checkpoint.redis.ashallow import AsyncShallowRedisSaver
RedisStore
✓ from langgraph.store.redis import RedisStore
This quickstart demonstrates how to integrate `RedisSaver` with a basic LangGraph `StateGraph`. It sets up a Redis connection, initializes the `RedisSaver` (including calling `.setup()` for index creation), and then compiles a simple graph to persist its state across invocations using a `thread_id`.
import os
from typing import Annotated
from langgraph.graph import StateGraph, START
from langgraph.checkpoint.redis import RedisSaver
from langchain_core.messages import BaseMessage, HumanMessage, AIMessage
# Set up Redis connection string, e.g., 'redis://localhost:6379/0'
REDIS_URL = os.environ.get('REDIS_URL', 'redis://localhost:6379/0')
# Define your graph state
class AgentState:
messages: Annotated[list[BaseMessage], lambda x, y: x + y]
# Define a simple node
def simple_agent_node(state: AgentState) -> dict:
new_message = AIMessage(content=f"Echo: {state.messages[-1].content}")
return {"messages": [new_message]}
# Create the Redis Checkpoint Saver
# Make sure Redis is running and accessible at REDIS_URL
# For production, ensure RedisJSON and RediSearch modules are enabled (Redis 8.0+ includes them)
with RedisSaver.from_conn_string(REDIS_URL) as checkpointer:
# Important: Call setup() to initialize required RediSearch indices
checkpointer.setup()
# Build the graph
workflow = StateGraph(AgentState)
workflow.add_node("agent", simple_agent_node)
workflow.set_entry_point(START)
workflow.set_finish_point("agent")
# Compile the graph with the checkpointer
app = workflow.compile(checkpointer=checkpointer)
# Example usage with a specific thread_id for persistence
thread_id = "test_conversation_123"
config = {"configurable": {"thread_id": thread_id}}
print(f"\n--- Invoking agent for thread: {thread_id} ---")
inputs = {"messages": [HumanMessage(content="Hello LangGraph with Redis!")]}
result = app.invoke(inputs, config)
print("Result 1:", result)
print(f"\n--- Invoking agent again for the same thread: {thread_id} ---")
inputs = {"messages": [HumanMessage(content="How are you doing?")]}
result = app.invoke(inputs, config)
print("Result 2:", result)
# List checkpoints (optional)
print(f"\n--- Checkpoints for thread {thread_id} ---")
for checkpoint in checkpointer.list(config):
print(checkpoint)
Debug
Known issues
breakingVersion 0.1.0 introduced breaking changes to the internal storage format. Checkpoints created with pre-0.1.0 versions are not readable by 0.1.0+ without manual migration.fixFor new deployments, start with version 0.1.0 or newer. For existing data, migration is not automatically supported; consider clearing old checkpoints or using new thread IDs.
affects: <0.1.0 to 0.1.0+
gotchaRedis requires the 'RedisJSON' and 'RediSearch' modules to be enabled for `langgraph-checkpoint-redis` functionality, especially for index creation and efficient data access. Redis 8.0+ includes these by default.fixEnsure your Redis instance (local, Redis Stack, or managed service) has RedisJSON and RediSearch modules enabled. For Redis < 8.0, use Redis Stack or install modules separately. Failure to do so will result in errors during `.setup()` or checkpoint operations.
affects: All versions
gotchaThe `.setup()` method must be called on RedisSaver/AsyncRedisSaver instances upon initial setup or application start to create necessary RediSearch indices. Failure to do so will lead to runtime errors.fixAlways call `checkpointer.setup()` (for synchronous) or `await checkpointer.asetup()` (for asynchronous) after creating your `RedisSaver` or `AsyncRedisSaver` instance.
affects: All versions
gotchaPotential data loss due to Redis persistence settings. Default Redis configurations might not guarantee durability if Redis crashes unexpectedly before RDB snapshot or AOF write operations complete.fixTune Redis persistence settings: use `save` directives (e.g., `save 60 100`), enable AOF (`appendonly yes`) with `appendfsync everysec`, and consider using both RDB and AOF with `aof-use-rdb-preamble yes`. For high availability, consider Redis Sentinel or Redis Cluster.
affects: All versions
gotchaIncorrect message serialization can lead to `MESSAGE_COERCION_FAILURE` errors when using LangGraph's checkpointers. This often happens when `message.to_dict()` is stored instead of `BaseMessage` objects or simple `{role, content}` dicts.fixEnsure that `BaseMessage` objects or `{role, content}` dictionaries are passed directly to the state or event streams, and avoid explicit calls to `message.to_dict()` for persistence. affects: All versions (especially with LangGraph v0.6.4+)
gotchaHigh memory usage in Redis deployments can lead to latency, failed runs, or Out of Memory (OOM) errors, especially in high-load or limited-resource environments.fixMonitor Redis memory usage. Implement TTL (Time To Live) settings for checkpoints (e.g., `defaultTTL` when creating saver) to manage data retention. Use `ShallowRedisSaver` for memory-optimized scenarios. Consider increasing Redis memory limits or using production-grade Redis deployments.
affects: All versions
gotchaCompatibility issues have been reported with Valkey (a Redis fork), which may cause hanging requests and connection problems.fixIt is strongly recommended to use a genuine Redis instance instead of Valkey for reliable operation with `langgraph-checkpoint-redis`.
affects: All versions when used with Valkey
Upgrade
Version history
0.5.2latest on PyPI · released Aug 20, 2026
Audit
Dependencies
redis>=5.2.1requiredRequired for Redis client communication.
redisvl>=0.5.1optionalRequired for vector search capabilities when using RedisStore.
langgraph-checkpoint>=2.0.24requiredProvides the base interface for LangGraph checkpointers.
langgraph>=0.3.0requiredThe core LangGraph framework.