LangChain Mastery

Course Content

LangChain Mastery

7 sections · 109 lessons

Write a function to handle version compatibility in LangChain.

What you need to know

The package map (as of 2026)

PackageContains
langchain-coreBase interfaces: runnables, messages, prompts, tools, callbacks, vector-store interface
langchain (1.x)create_agent, middleware, init_chat_model, tools and messages re-exports
langchain-classicLegacy chains (LLMChain, RetrievalQA), retrievers like EnsembleRetriever, indexing API helpers, hub, CacheBackedEmbeddings
langgraphThe runtime agents run on: graphs, checkpointers, streaming
langchain-openai, langchain-anthropic, langchain-chroma, ...One package per integration
langchain-communityCommunity integrations (loaders, some stores and retrievers)

In September 2026 the current lines are langchain 1.4, langchain-core 1.6 and langgraph 1.2 — check PyPI for exact numbers when you answer.

A startup check

Python
from importlib.metadata import version, PackageNotFoundErrorfrom packaging.specifiers import SpecifierSetREQUIRED = {    "langchain": ">=1.0,<2",    "langchain-core": ">=1.0,<2",    "langchain-openai": ">=1.0,<2",    "langgraph": ">=1.0,<2",}def check_versions(required: dict[str, str] = REQUIRED) -> list[str]:    problems = []    for pkg, spec in required.items():        try:            found = version(pkg)        except PackageNotFoundError:            problems.append(f"{pkg} is not installed (need {spec})")            continue        if found not in SpecifierSet(spec):            problems.append(f"{pkg} {found} does not satisfy {spec}")    return problemsif problems := check_versions():    raise RuntimeError("Incompatible LangChain install: " + "; ".join(problems))

packaging (already a dependency of langchain-core) compares versions correctly, including pre-releases, which naive string or tuple comparison gets wrong.

Upgrade practice

  1. Pin everything in a lockfile (uv.lock, poetry.lock, or pip-compile output).
  2. Read the migration guide for major versions; 1.0 has one.
  3. Turn warnings into errors in CI (-W error::DeprecationWarning for your own code paths) to find deprecated calls before they are removed.
  4. Upgrade core and partners together, then run unit tests and the evaluation dataset.
  5. Roll out gradually and compare traces before and after.

The 1.0 changes to know

  • from langchain.chains import ... → from langchain_classic.chains import ... (or rewrite in LCEL).
  • initialize_agent, AgentExecutor, create_react_agent → create_agent from langchain.agents, with system_prompt= and middleware.
  • langchain.globals → langchain_core.globals.
  • Python 3.9 dropped.

A real-life example

An HR bot's Dockerfile had pip install langchain with no pin. A rebuild in November 2025 pulled 1.0, and the service failed at import: from langchain.chains import create_retrieval_chain no longer existed. The team hot-fixed by pinning langchain<1.0.

They then planned the migration: added langchain-classic to get running on 1.x the same day, replaced the retrieval chain with LCEL, rewrote the leave-filing AgentExecutor as create_agent with HumanInTheLoopMiddleware for approvals, added the startup check and a lockfile, and ran their 120-question evaluation set before and after. Scores matched within one point, and the upgrade shipped a week later.

Follow-up questions to expect

  • "Why can't you upgrade just langchain-openai?" — Partner packages require a matching langchain-core range; mixing versions causes import errors or subtle behaviour changes.
  • "How do you handle a deprecated API you depend on?" — Wrap it behind your own function so there is one place to change, and schedule the migration before the removal version.
  • "Is langchain-classic long-term?" — It exists for compatibility; treat it as a bridge and move to current APIs over time.