Heuristic:Langchain ai Langchain Deprecation Version Tracking
| Knowledge Sources | |
|---|---|
| Domains | API_Design, Maintenance |
| Last Updated | 2026-02-11 14:00 GMT |
Overview
LangChain's deprecation system uses `since`, `removal`, `alternative`, and `pending` fields to manage the lifecycle of deprecated APIs with clear migration paths.
Description
The `@deprecated` decorator in `langchain_core._api.deprecation` provides a structured way to deprecate APIs. It issues `LangChainDeprecationWarning` (or `LangChainPendingDeprecationWarning` for pending deprecations) with version tracking, alternative suggestions, and import redirects. A `suppress_langchain_deprecation_warning()` context manager is provided for tests and internal usage.
Usage
Apply this heuristic when deprecating any public API in a LangChain package, or when consuming deprecated APIs and needing to suppress warnings during testing.
The Insight (Rule of Thumb)
- Action: Use the `@deprecated()` decorator with all four fields: `since`, `removal`, `alternative`, `alternative_import`.
- Value: `pending=True` for APIs without a firm removal date. `pending=False` (default) for APIs with a scheduled removal version.
- Trade-off: Deprecation warnings add noise to user output. Use `suppress_langchain_deprecation_warning()` in tests to keep output clean.
- Pattern: Always provide `alternative` or `alternative_import` to guide users to the replacement API.
Reasoning
LangChain's rapid evolution means APIs change frequently. Without structured deprecation, users face silent breakage on upgrades. The four-field system ensures:
- `since`: Users know when the deprecation started (for changelogs).
- `removal`: Users know their deadline to migrate.
- `alternative`: Users know what to use instead.
- `pending`: Distinguishes "will be removed eventually" from "will be removed in version X".
The suppression context manager is critical for tests — deprecated APIs still need test coverage until removal, but the warnings would pollute test output.
Code evidence from `libs/core/langchain_core/_api/deprecation.py:89-143`:
@deprecated(
since: str,
message: str = "",
alternative: str = "",
alternative_import: str = "",
pending: bool = False,
removal: str = "",
)
Warning classes from `libs/core/langchain_core/_api/deprecation.py:51-56`:
class LangChainDeprecationWarning(DeprecationWarning):
"""A class for issuing deprecation warnings for LangChain users."""
class LangChainPendingDeprecationWarning(PendingDeprecationWarning):
"""A class for issuing pending deprecation warnings for LangChain users."""
Suppression utility from `libs/core/langchain_core/_api/deprecation.py:430-435`:
@contextlib.contextmanager
def suppress_langchain_deprecation_warning() -> Generator[None, None, None]:
with warnings.catch_warnings():
warnings.simplefilter("ignore", LangChainDeprecationWarning)
warnings.simplefilter("ignore", LangChainPendingDeprecationWarning)
yield
Real usage example from `libs/core/langchain_core/utils/aiter.py:37`:
@deprecated(since="1.1.2", removal="2.0.0")
def py_anext(...)