Upgrade to Langfuse v4
Langfuse v4 uses an observations-first data model. The v4 overview explains what changed. New managed projects already use v4 and need no migration.
For existing projects, complete the applicable steps below.
1. Upgrade trace ingestion
Move off legacy ingestion before the v4 cutover. Deprecated SDKs can delay data by up to 10 minutes.
| Your setup | Do this |
|---|---|
| Python SDK below 4.7.0 | Upgrade the Python SDK to 4.7.0 or later. |
| JS/TS SDK below 5.4.0 | Upgrade the JS/TS SDK to 5.4.0 or later. |
| Custom REST or OpenTelemetry ingestion | Migrate custom ingestion to the v4 OTLP/HTTP path. |
2. Migrate the v3 features you use
Only follow the rows that apply to your project.
| Check | Do this |
|---|---|
| APIs | Migrate deprecated API calls to the supported Observations, Metrics, Scores, and Experiments APIs. |
| Evaluators | Move trace-level evaluators to observation targets and legacy-dataset evaluators to experiment targets. |
| Exports | Switch blob storage exports to enriched observations. |
| Integrations | Switch PostHog and Mixpanel to enriched observations. |
3. Complete the rollout
Managed projects
Langfuse Cloud becomes v4-only on November 9, 2026. Complete every action detected for your projects before this date. Follow the v4 timeline for rollout updates.
If the sidebar still shows the Langfuse v4 preview toggle, enable it. Organization owners can then open Migration status to review every project in their organizations. The page flags the specific SDK, evaluator, experiment, API, or export work required for each project.
Self-hosted deployments
Self-hosted v4 is generally available. Follow the v3 to v4 upgrade guide to migrate your deployment; the legacy and dual write modes let you schedule each migration step independently.
There is no forced cutover date. Langfuse v3 receives security patches through January 2027. The self-hosted compatibility matrix lists supported SDKs and APIs.
Questions
Ask rollout and migration questions in the v4 GitHub Discussion; we use that thread for updates and answers.
Last edited
