| name | langfuse-upgrade-migration |
| description | Upgrade Langfuse SDK versions and migrate between API changes.
Use when upgrading Langfuse SDK, handling breaking changes,
or migrating between Langfuse versions.
Trigger with phrases like "upgrade langfuse", "langfuse migration",
"update langfuse SDK", "langfuse breaking changes", "langfuse version".
|
| allowed-tools | Read, Write, Edit, Bash(npm:*), Bash(pip:*) |
| version | 1.12.0 |
| license | MIT |
| author | Jeremy Longshore <jeremy@intentsolutions.io> |
| tags | ["saas","langfuse","api","migration"] |
| compatibility | Designed for Claude Code |
Langfuse Upgrade & Migration
Current State
!npm list langfuse @langfuse/client @langfuse/tracing @langfuse/otel 2>/dev/null | head -10 || echo 'No langfuse packages found'
!pip show langfuse 2>/dev/null | grep -E "Name|Version" || echo 'Python langfuse not installed'
Overview
Step-by-step guide for upgrading the Langfuse SDK across major versions. Covers v3 to v4 (OTel rewrite), v4 to v5, breaking changes, and automated codemods.
Prerequisites
- Existing Langfuse integration
- Test suite covering traced operations
- Git branch for the upgrade
Version Roadmap
| SDK | Package | Architecture | Status |
|---|
| v3 | langfuse (single) | Custom, Langfuse class | Legacy |
| v4 | @langfuse/client, @langfuse/tracing, @langfuse/otel | OpenTelemetry-based | Stable |
| v5 | @langfuse/client, @langfuse/tracing, @langfuse/otel | OpenTelemetry + improvements | Latest |
Instructions
Step 1: Check Current Version and Plan
set -euo pipefail
npm list langfuse @langfuse/client @langfuse/tracing 2>/dev/null
npm info @langfuse/client version
npm info @langfuse/tracing version
npm info langfuse version
pip show langfuse 2>/dev/null | grep Version
pip index versions langfuse 2>/dev/null | head -3
Step 2: v3 to v4 Migration (TypeScript)
This is the biggest migration -- v4 rewrites tracing on OpenTelemetry.
2a. Install new packages:
set -euo pipefail
npm install @langfuse/client @langfuse/tracing @langfuse/otel @opentelemetry/sdk-node
