{"id":772,"library":"langgraph-checkpoint","title":"LangGraph Checkpoint Base Interfaces","description":"LangGraph-checkpoint provides the base interfaces for checkpoint savers within the LangGraph framework (version 4.0.1). It defines the fundamental persistence layer, allowing LangGraph agents to save and restore their state across interactions, which is crucial for features like human-in-the-loop workflows, conversational memory, and time-travel debugging. This library also includes a default in-memory checkpointer for testing and experimentation. It releases frequently, often in conjunction with the main `langgraph` library.","status":"active","version":"4.0.1","language":"python","source_language":"en","source_url":"https://github.com/langchain-ai/langgraph/tree/main/libs/checkpoint","tags":["langgraph","checkpoint","persistence","state management","LLM agents","AI","conversational AI"],"install":[{"cmd":"pip install langgraph-checkpoint","lang":"bash","label":"Install base library"}],"dependencies":[{"reason":"Core framework that utilizes these checkpoint interfaces.","package":"langgraph","optional":false},{"reason":"Common persistent checkpointer for local workflows and demos.","package":"langgraph-checkpoint-sqlite","optional":true},{"reason":"Robust persistent checkpointer recommended for production environments.","package":"langgraph-checkpoint-postgres","optional":true},{"reason":"AWS-specific persistence solution with various backends.","package":"langgraph-checkpoint-aws","optional":true}],"imports":[{"note":"Due to the transition to namespace packages, direct re-exported imports from `langgraph.checkpoint` are no longer supported since LangGraph v0.2 / langgraph-checkpoint v1.0.0.","wrong":"from langgraph.checkpoint import BaseCheckpointSaver","symbol":"BaseCheckpointSaver","correct":"from langgraph.checkpoint.base import BaseCheckpointSaver"},{"note":"The in-memory saver is provided for development and testing.","symbol":"InMemorySaver","correct":"from langgraph.checkpoint.memory import InMemorySaver"},{"note":"The default serializer for checkpoint data, handling various Python types.","symbol":"JsonPlusSerializer","correct":"from langgraph.checkpoint.serde.jsonplus import JsonPlusSerializer"}],"quickstart":{"code":"import os\nfrom typing_extensions import TypedDict\nfrom langgraph.graph import StateGraph, START, END\nfrom langgraph.checkpoint.memory import InMemorySaver\n\n# Define the state for the graph\nclass AgentState(TypedDict):\n    messages: list[str]\n\n# Define a simple node\ndef chat_node(state: AgentState) -> AgentState:\n    # In a real agent, this would involve LLM calls or tool execution\n    print(f\"Processing: {state['messages'][-1]}\")\n    new_message = f\"Echo: {state['messages'][-1]}\"\n    return {\"messages\": state[\"messages\"] + [new_message]}\n\n# Build the graph\nbuilder = StateGraph(AgentState)\nbuilder.add_node(\"echo_chat\", chat_node)\nbuilder.add_edge(START, \"echo_chat\")\nbuilder.add_edge(\"echo_chat\", END)\n\n# Initialize the in-memory checkpointer\ncheckpointer = InMemorySaver()\n\n# Compile the graph with the checkpointer\n# A real LangGraph application would likely use a more complex graph and invoke it\n# to test persistence.\n# For this quickstart, we just demonstrate setup.\ngraph = builder.compile(checkpointer=checkpointer)\n\n# Example of how you would invoke (not part of langgraph-checkpoint itself, but for context)\n# config = {\"configurable\": {\"thread_id\": \"1\"}}\n# inputs = {\"messages\": [\"Hello LangGraph!\"]}\n# result = graph.invoke(inputs, config=config)\n# print(result)","lang":"python","description":"This quickstart demonstrates how to set up a basic `StateGraph` and configure it with the `InMemorySaver` from `langgraph-checkpoint`. The `InMemorySaver` is suitable for local development and testing, saving state in memory. For persistent storage, you would typically use an external checkpointer like `PostgresSaver` or `SqliteSaver` from their respective `langgraph-checkpoint-*` libraries."},"warnings":[{"fix":"Replace `thread_ts` with `checkpoint_id` in your graph configuration (e.g., `{\"configurable\": {\"thread_id\": \"1\", \"checkpoint_id\": \"some_uuid\"}}`).","message":"The `thread_ts` parameter was renamed to `checkpoint_id` in `langgraph-checkpoint` v1.0.0. While `thread_ts` is currently still recognized, it's deprecated. Update your code to use `checkpoint_id` for clarity and future compatibility.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Change import statements from `from langgraph.module import Symbol` to `from langgraph.module.submodule import Symbol` (e.g., `from langgraph.checkpoint.base import BaseCheckpointSaver`, `from langgraph.graph.state import StateGraph`).","message":"Due to the move to namespace packages, direct imports from top-level `langgraph` modules (e.g., `langgraph.checkpoint`, `langgraph.graph`) are no longer valid. You must use the fully qualified path for the specific sub-module.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Always include `{\"configurable\": {\"thread_id\": \"your_unique_thread_id\"}}` in your `graph.invoke()` or `graph.stream()` calls.","message":"When using any checkpointer, `thread_id` is a mandatory configuration parameter for graph invocations to enable state persistence. Without it, the checkpointer cannot save or retrieve state.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure you call `checkpointer.setup()` (or `await checkpointer.asetup()` for async) after initializing a database checkpointer.","message":"For database-backed checkpointers (e.g., SQLite, PostgreSQL, MySQL), the `.setup()` method must be called on the checkpointer instance to create necessary tables before first use.","severity":"gotcha","affected_versions":"All versions of database checkpointer implementations"},{"fix":"Ensure that any objects stored in checkpoint metadata are JSON serializable. Convert complex Python objects to their JSON-compatible representations before storing them, or move non-JSON data to dedicated channel blobs.","message":"In `langgraph-checkpoint-postgres` versions 2.0.22 and higher, metadata serialization changed. Non-JSON serializable objects (e.g., `HumanMessage` instances directly) stored in checkpoint metadata will now raise errors, as metadata is passed as JSONB.","severity":"gotcha","affected_versions":"langgraph-checkpoint-postgres >= 2.0.22"},{"fix":"Immediately update to the latest versions of `langgraph-checkpoint` and any specific `langgraph-checkpoint-*` backend libraries you are using. Review your usage of community-contributed checkpointers for similar vulnerabilities.","message":"Security vulnerabilities (CVE-2026-28277 for unsafe msgpack deserialization and CVE-2026-27022 for Redis query injection) have been disclosed impacting LangGraph's checkpoint system for certain backend implementations. These can lead to remote code execution or query injection.","severity":"breaking","affected_versions":"Specific backend implementations (e.g., `@langchain/langgraph-checkpoint-redis` prior to 1.0.2) and potentially others using msgpack serialization."}],"env_vars":null,"last_verified":"2026-05-12T18:52:53.392Z","next_check":"2026-06-27T00:00:00.000Z","problems":[{"fix":"Install the required package, for example: `pip install langgraph-checkpoint-sqlite` or `pip install langgraph-checkpoint-postgres`.","cause":"Specific checkpointer implementations like `SqliteSaver` or `PostgresSaver` are not part of the base `langgraph-checkpoint` library but are provided by separate, optional packages (`langgraph-checkpoint-sqlite` or `langgraph-checkpoint-postgres`) which need to be installed explicitly.","error":"ModuleNotFoundError: No module named 'langgraph.checkpoint.sqlite'"},{"fix":"Instantiate a `BaseCheckpointSaver` (e.g., `InMemorySaver` for development or a production-grade saver like `PostgresSaver`) and pass it to the `compile()` method: `checkpointer = InMemorySaver()` `graph = builder.compile(checkpointer=checkpointer)`.","cause":"The LangGraph application attempts to use persistence functionality (e.g., saving state) but no checkpointer instance has been provided to the graph's `compile()` method or `@entrypoint` decorator.","error":"MISSING_CHECKPOINTER"},{"fix":"Properly use the context manager with a `with` statement to obtain the actual `PostgresSaver` instance: `with PostgresSaver.from_conn_string(DB_URI) as checkpointer: checkpointer.setup() # Now setup() is called on the actual saver instance`.","cause":"When using `PostgresSaver.from_conn_string()` (or similar `from_conn_string` methods), it returns a context manager, not the `PostgresSaver` instance itself. Attempting to call methods like `setup()` directly on this context manager will result in an `AttributeError` or `TypeError`.","error":"AttributeError: '_GeneratorContextManager' object has no attribute 'get_next_version'"},{"fix":"Reduce the size of the application state saved to checkpoints, avoid storing large binary data directly in the state (instead, store references to external storage), or consider switching to a database backend like PostgreSQL which supports larger field sizes.","cause":"This error typically occurs when using a checkpointer with a backend like MongoDB, which has a 16MB document size limit. Storing large amounts of data or binary objects directly in the graph state can quickly exceed this limit as a new checkpoint is saved at every super-step.","error":"\"DocumentTooLarge\" errors during checkpoint saves"}],"ecosystem":"pypi","meta_description":null,"install_score":100,"install_tag":"verified","quickstart_score":0,"quickstart_tag":"stale","pypi_latest":"4.1.0","cli_name":"","cli_version":null,"install_checks":{"last_tested":"2026-05-12","tag":"verified","tag_description":"installs cleanly on critical runtimes, fast import, recently tested","installed_version":null,"pypi_latest":"4.1.0","is_stale":null,"results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"langgraph-checkpoint","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":1.26,"mem_mb":21,"disk_size":"64.8M"},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"langgraph-checkpoint","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":1.29,"mem_mb":20.9,"disk_size":"63.9M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"langgraph-checkpoint","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":null,"install_time_s":7.9,"import_time_s":0.91,"mem_mb":20.9,"disk_size":"73M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"langgraph-checkpoint","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.89,"mem_mb":20.8,"disk_size":"72M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"langgraph-checkpoint","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":1.57,"mem_mb":22.6,"disk_size":"70.1M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"langgraph-checkpoint","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":1.75,"mem_mb":22.4,"disk_size":"69.1M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"langgraph-checkpoint","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":null,"install_time_s":6.7,"import_time_s":1.36,"mem_mb":22.6,"disk_size":"78M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"langgraph-checkpoint","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":1.31,"mem_mb":22.4,"disk_size":"77M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"langgraph-checkpoint","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":1.72,"mem_mb":21.7,"disk_size":"61.1M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"langgraph-checkpoint","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":1.78,"mem_mb":21.6,"disk_size":"60.1M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"langgraph-checkpoint","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":null,"install_time_s":5.5,"import_time_s":1.63,"mem_mb":21.7,"disk_size":"69M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"langgraph-checkpoint","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":1.68,"mem_mb":21.6,"disk_size":"68M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"langgraph-checkpoint","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":1.51,"mem_mb":22.6,"disk_size":"60.9M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"langgraph-checkpoint","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":1.6,"mem_mb":22.4,"disk_size":"59.7M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"langgraph-checkpoint","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":null,"install_time_s":5.7,"import_time_s":1.49,"mem_mb":22.6,"disk_size":"69M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"langgraph-checkpoint","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":1.59,"mem_mb":22.4,"disk_size":"68M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"langgraph-checkpoint","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":1.59,"mem_mb":24.3,"disk_size":"61.4M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"langgraph-checkpoint","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":1.56,"mem_mb":24.3,"disk_size":"61.4M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"langgraph-checkpoint","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":null,"install_time_s":8.3,"import_time_s":1.51,"mem_mb":24.3,"disk_size":"69M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"langgraph-checkpoint","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":1.34,"mem_mb":24.3,"disk_size":"69M"}]},"quickstart_checks":{"last_tested":"2026-04-24","tag":"stale","tag_description":"widespread failures or data too old to trust","results":[{"runtime":"python:3.10-alpine","exit_code":1},{"runtime":"python:3.10-slim","exit_code":1},{"runtime":"python:3.11-alpine","exit_code":1},{"runtime":"python:3.11-slim","exit_code":1},{"runtime":"python:3.12-alpine","exit_code":1},{"runtime":"python:3.12-slim","exit_code":1},{"runtime":"python:3.13-alpine","exit_code":1},{"runtime":"python:3.13-slim","exit_code":1},{"runtime":"python:3.9-alpine","exit_code":1},{"runtime":"python:3.9-slim","exit_code":1}]}}