Versions & Compatibility
Reference for how Langfuse's server, SDK, and API versions relate across Langfuse Cloud and self-hosted deployments.
Langfuse v4 is generally available: the self-hosted release ships soon, and Langfuse Cloud, where v4 has been rolling out in preview since March 2026, will switch to v4 as the only experience, at which point remaining legacy APIs and ingestion paths are also removed. Exact dates will follow.
The compatibility rule: each Langfuse server major version aims to support the current and the previous SDK major version of each language. New SDK versions require a recent server version, as some features may not be available on older servers; see the feature availability matrix.
We try very hard to uphold this rule. v4 breaks backwards compatibility with older SDKs; see the Langfuse v4 page for all information.
| Deployment | How versioning works |
|---|---|
| Langfuse Cloud | Always runs the latest Langfuse version; server versions are managed for you. Only your SDK version and the API endpoints you call matter; the self-hosted server minimums on this page do not apply. Breaking removals happen on published dates. |
| Self-hosted (OSS & Enterprise) | You choose when to upgrade the server. New capabilities are battle-tested on Langfuse Cloud before they ship in a self-hosted release, so Cloud can run ahead of the latest self-hosted version. SDK majors require the minimum server versions in the self-hosted compatibility matrix; breaking removals only happen in major server releases (see the versioning policy and upgrade documentation). |
Langfuse versions
Every Langfuse component (server, SDKs, and APIs) moves through these lifecycle stages:
| Stage | Meaning |
|---|---|
| Preview | New capabilities that are production-ready, but interfaces or API design may still change. |
| GA | Recommended and fully supported. |
| Deprecated | Still works but is superseded; removal is noted in the matrix below. Migrate to the replacement. |
| End of life | Unsupported, no security patches. |
GA versions
| Component | GA version | Package / repo | Notes |
|---|---|---|---|
| Server | v4 | langfuse/langfuse  | Observations-first data model; v3 continues to receive security patches |
| Python SDK | v4 | langfuse  | OpenTelemetry-based since v3. Requires Python 3.9+. |
| JS/TS SDK | v5 | @langfuse/*  | OpenTelemetry-based since v4. Requires Node.js 20+. |
| Other languages | n/a | OpenTelemetry | Any OTel SDK to the Langfuse OTel endpoint |
Feature availability matrix
Langfuse Cloud runs v3 and v4 side by side until the v4 cutover (dates will follow). The v3 column is deprecated: everything marked Deprecated below keeps working until the cutover and is then removed. Click a row for details.
Self-hosting Langfuse? Use the self-hosted compatibility matrix instead; it covers each server version and the minimum server version per SDK.
Frequently asked questions
I'm on Langfuse Cloud, which versions do I need to care about?
Only your SDK version and the API endpoints you call. Langfuse Cloud always runs the latest server version, so self-hosted server minimums never apply to you. Keep your SDKs on the GA major version (Python v4, JS/TS v5) and migrate away from deprecated endpoints before the v4 cutover (dates will follow).
I self-host Langfuse v3 and upgraded to Python SDK v4 / JS SDK v5, what works?
Tracing, prompt management, datasets, and scores work fully (server ≥ 3.125.0 for Python, ≥ 3.95.0 for JS/TS). The default api.observations and api.metrics resources call v2 endpoints that require Langfuse v4; use the api.legacy.* resources until you upgrade your server to v4. The self-hosted compatibility matrix has the full picture per server version.
My data takes minutes to show up in the UI, why?
On the v4 data model, data from Python SDK < 4.0.0, JS SDK < 5.0.0, or OTel exporters without the x-langfuse-ingestion-version: 4 header can be delayed by up to 10 minutes. Upgrade to Python SDK ≥ 4.7.0 / JS SDK ≥ 5.4.0 (or set the header) for real-time data.
When do old SDKs stop working on Langfuse Cloud?
Python SDK v2 and JS/TS SDK v3 (and older) send traces via the legacy batch ingestion API, which is removed on Langfuse Cloud at the v4 cutover (date will follow). Upgrade to the GA SDK majors now; see the SDK upgrade paths.
Does upgrading my self-hosted server break my SDKs?
Each server major supports the current and previous SDK major of each language. Upgrading v3 → v4 keeps Python SDK v3+/v4 and JS SDK v4/v5 working (older SDKs lose real-time visibility; Python v2 / JS v3 trace ingestion is not supported on v4). Check the self-hosted compatibility matrix before upgrading.
Last edited
