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 and legacy-dataset evaluators to observation-level evaluators. |
| 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 Preview, 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 currently a release candidate. Use the v3 to v4 upgrade guide to test the migration in staging, but wait for a stable v4 release before migrating production.
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
Use the general v4 discussion for managed rollout questions and the self-hosted v4 discussion for server migration questions.
Last edited
