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
The managed cutover date has not been announced. Follow the v4 timeline for updates.
If the sidebar still shows the Langfuse v4 preview toggle, enable it. Then open Action required to view the project checklist. Each category shows Up to date, Not detected, or the number of affected items.
Select Migration Status to review organization-wide progress. The page shows the migrated-project count and each project's status, SDK, affected evaluators, APIs, exports, and latest trace.
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
