LangChain 버전 관리

LangChain 버전 관리 (Versioning)

LangChain과 LangGraph의 오픈소스 패키지는 Semantic Versioning 방식을 따라 MAJOR.MINOR.PATCH 형태로 버전이 매겨져요. 이 글에서는 버전 번호가 무엇을 의미하는지, API 안정성 단계가 어떻게 나뉘는지, 릴리스·지원 정책이 어떻게 돌아가는지 정리해 드릴게요.

출처: 공식문서

버전 번호의 의미

OSS 버전 번호는 Semantic Versioning에서 정의한 MAJOR.MINOR.PATCH 형식을 따르는데요.

  • Major: 코드 변경이 필요한, 호환되지 않는 API 업데이트
  • Minor: 이전 버전과 호환성을 유지한 채 추가되는 새 기능과 개선
  • Patch: 버그 수정과 사소한 개선

예를 들어 1.0.0은 프로덕션에 쓸 수 있는 첫 안정 릴리스, 1.1.0은 하위 호환되는 새 기능 추가, 1.0.1은 하위 호환되는 버그 수정을 뜻해요.

API 안정성

특별한 접두어가 없는 모든 API는 안정(stable) API로 보고 프로덕션에서 사용할 수 있어요. 안정 기능은 하위 호환을 유지하며, 호환되지 않는 변경은 메이저 릴리스에서만 도입돼요.

  • Beta: 기능은 완성됐지만 사용자 피드백에 따라 작은 변경이 있을 수 있어요. 프로덕션에 써도 안전하지만 이후 릴리스에서 사소한 조정이 필요할 수 있죠.
  • Alpha: 실험 단계라 크게 바뀔 수 있어요. 프로덕션에서 쓰려면 주의가 필요해요.
  • Deprecated: 향후 메이저 릴리스에서 제거될 예정이에요. 권장 대체 API로 전환하고, 메이저 릴리스와 함께 나오는 마이그레이션 가이드를 따라가세요.
  • Internal(내부): 문서가 internal이라고 명시하거나, 앞에 밑줄(_)로 시작하는 함수/메서드는 내부 API로 언제든 바뀔 수 있어요. 다만 구현 없이 하위 클래스에서 override할 목적의 _ 접두어 메서드는 LangChain의 Public API로 간주돼요.

릴리스 주기

  • Major 릴리스(예: 1.0.0 → 2.0.0): 호환되지 않는 API 변경, 폐기 기능 제거, 아키텍처 개선이 포함돼요. 상세한 마이그레이션 가이드, 가능한 자동화 도구, 이전 메이저 버전의 확장 지원 기간을 제공해요.
  • Minor 릴리스(예: 1.0.0 → 1.1.0): 새 기능, 성능 개선, 새 선택 파라미터, 하위 호환 개선.
  • Patch 릴리스(예: 1.0.0 → 1.0.1): 버그 수정, 보안 업데이트, 문서 개선, API 변화 없는 성능 최적화.

버전 지원 정책

  • 최신 메이저 버전: 활발히 개발되는 완전 지원(ACTIVE 상태)
  • 직전 메이저 버전: 다음 메이저 릴리스 이후 12개월 동안 보안 업데이트와 중요 버그 수정(MAINTENANCE 상태)
  • 그 이전 버전: 커뮤니티 지원만 제공

장기 지원(LTS) 릴리스

LangChain과 LangGraph 모두 1.0을 LTS 릴리스로 지정했어요. 1.0은 2.0이 릴리스될 때까지 ACTIVE 상태를 유지하고, 2.0 출시 후에는 최소 1년간 MAINTENANCE 모드에 들어가요. LTS 릴리스는 semver를 따르며 마이너 버전 간 안전하게 업그레이드할 수 있어요. 기존 버전인 LangChain 0.3과 LangGraph 0.4는 2026년 12월까지 MAINTENANCE 모드예요.

1.0 이전 패키지

Deep Agents(deepagents)는 1.0 이전의 활발히 개발 중인 패키지예요. API가 마이너 버전 사이에서도 바뀔 수 있으며, 가능하면 호환 깨짐을 최소화해요. 1.0에 도달한 뒤에는 LangChain·LangGraph와 같은 LTS 정책을 따를 예정이에요.

내 버전 확인하기

import langchain_core
print(langchain_core.__version__)

import langgraph
print(langgraph.__version__)

업그레이드하기

# 최신 버전으로
pip install -U langchain-core langchain
# 특정 버전으로
pip install langchain-core==1.0.0

pip install -U langgraph
pip install langgraph==1.0.0

pip install -U deepagents
pip install deepagents==0.1.0

사전 릴리스 버전

  • Alpha(예: 1.0.0a1): 초기 프리뷰, 큰 변경 예상
  • Beta(예: 1.0.0b1): 기능 완성, 사소한 변경 가능
  • Release Candidate(예: 1.0.0rc1): 안정 릴리스 전 최종 테스트

더 알아보기 (Learn more)