Principle:Langchain ai Langgraph Deprecation Management
| Attribute | Value |
|---|---|
| Type | Principle |
| Knowledge Sources | LangGraph |
| Domains | Core, Deprecation, API_Lifecycle |
| Last Updated | 2026-02-11 15:00 GMT |
Overview
Deprecation management in LangGraph provides a structured warning system that communicates when features are deprecated, which version introduced the deprecation, and when the deprecated functionality is expected to be removed.
Description
LangGraph implements a structured deprecation system inspired by Pydantic's `PydanticDeprecationWarning` pattern. The system is built on a hierarchy of warning classes that extend Python's built-in `DeprecationWarning`:
`LangGraphDeprecationWarning` is the base class for all LangGraph deprecation warnings. Each instance carries three pieces of information: the deprecation `message` (with trailing periods automatically stripped for consistent formatting), the `since` version tuple indicating when the deprecation was introduced (as `(major, minor)`), and the `expected_removal` version tuple indicating when the feature will be removed. If `expected_removal` is not explicitly specified, it defaults to the next major version (i.e., `(since[0] + 1, 0)`).
The `__str__` method produces a standardized format: `"{message}. Deprecated in LangGraph V{major}.{minor} to be removed in V{major}.{minor}."` This ensures all deprecation warnings follow a consistent, informative pattern.
Two convenience subclasses provide version-specific shortcuts:
- `LangGraphDeprecatedSinceV05` -- For features deprecated since LangGraph v0.5.0, expected removal in v2.0.0.
- `LangGraphDeprecatedSinceV10` -- For features deprecated since LangGraph v1.0.0, expected removal in v2.0.0.
These warning classes are used throughout the LangGraph codebase: in `constants.py` for deprecated import paths, in `errors.py` for the deprecated `NodeInterrupt` class, in `tool_validator.py` for the deprecated `ValidationNode`, and elsewhere.
Usage
Use the deprecation warning classes when removing or replacing public API surfaces. Issue warnings via `warnings.warn()` with the appropriate subclass and `stacklevel=2` to ensure the warning points to the caller's code rather than the internal implementation. When introducing a new deprecation, choose the subclass matching the current release version or create a new one if needed. Consumer code can filter these warnings using Python's standard `warnings` module filters.
Theoretical Basis
The deprecation management system implements the semantic versioning contract by making version lifecycle information machine-readable and programmatically accessible. Rather than relying solely on documentation to communicate deprecation timelines, the warning objects carry structured version metadata that enables automated tooling to detect and report upcoming breaking changes.
The inheritance hierarchy (`DeprecationWarning` -> `LangGraphDeprecationWarning` -> version-specific subclasses) follows the template method pattern: the base class defines the standard formatting and version-defaulting behavior, while subclasses only need to provide their specific version constants. This eliminates boilerplate and ensures consistency across all deprecation warnings in the framework.
The approach of encoding version information directly in the warning class (rather than just the message string) supports the progressive migration strategy: developers can filter warnings by version to prioritize migrations, addressing the most urgent deprecations (those closest to removal) first.