---
title: Versions & Compatibility
sidebarTitle: "Versions & Compatibility"
---
# Versions & Compatibility
Versioning is key to ensure compatibility between Langfuse Server, SDKs, and custom integrations via the Public API. Thus, we take [semantic versioning](https://semver.org/) seriously.
The [feature availability matrix](#sdk-server) below shows what each self-hosted server version supports. For Langfuse Cloud and an overview of current and legacy versions, see [Versions & Compatibility](/docs/compatibility).
## Scope of semantic versioning
The following changes **result in a major version bump** as they are considered breaking:
- Infrastructure changes
- Removal of existing Public APIs or removal/changes of existing parameters from Public APIs
The following changes **do not result in a major version bump** as they are considered internal implementation details:
- Database schemas
- Frontend APIs
## Compatibility between Langfuse Server and SDKs
Langfuse Server and SDKs are versioned independently to allow for more flexibility in upgrading components. The compatibility rule: **each server major version aims to support the current and the previous SDK major version of each language, and each SDK major requires a minimum server version.** We try extremely hard to uphold this rule, but the v4 transition is an exception: it ends support for older SDK majors on a published schedule (see the [feature availability matrix](#sdk-server)).
- **Server**: Can be upgraded independently of SDK versions within the supported range. Major server upgrades can drop support for old SDK majors; check the [feature availability matrix](#sdk-server) and the upgrade guide before upgrading.
- **SDKs**: Older SDK majors keep working on newer servers until they are deprecated and removed. New SDK majors require the minimum server versions listed in the [feature availability matrix](#sdk-server).
We recommend keeping the Langfuse Server up to date to ensure access to all features and security updates.
## How Langfuse Cloud is versioned [#cloud]
Langfuse Cloud deploys continuously and always runs the latest Langfuse version. 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, and some features may be enabled on Cloud before they are available self-hosted.
Consequences:
- On Cloud, server versions are managed for you; only SDK versions and API endpoints matter.
- Breaking removals on Cloud are announced with a migration window and happen on published dates; on self-hosted they only happen in major releases. Cloud removals are tracked in the [Langfuse Cloud matrix](/docs/compatibility#sdk-server), self-hosted support in the [matrix below](#sdk-server).
## Feature availability matrix [#sdk-server]
The matrix below shows what each self-hosted server major version supports: SDK majors with their minimum server versions, ingestion paths, read APIs, exports, and evaluators. Click a row for details and replacement endpoints.
On Langfuse Cloud, server versions are managed for you; use the [Langfuse Cloud matrix](/docs/compatibility#sdk-server) instead.
| Client | OSS v2 (End of life) | OSS v3 (Deprecated) | OSS v4 (GA) | Status |
| ------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- | --------------------------------------------------------------- | --------------------------------------------------------------- | ----------- |
| **Python** · [Upgrade guide](/docs/observability/sdk/upgrade-path) | | | | |
| Python SDK v4 | Unsupported | ≥ 3.63.0 | Full | GA |
| Python SDK v3 | Unsupported | ≥ 3.63.0 | Deprecated | Deprecated |
| Python SDK v2 | Full | Full | Unsupported | Deprecated |
| Python SDK v1 | Full | Unsupported | Unsupported | End of life |
| **JS/TS** · [Upgrade guide](/docs/observability/sdk/upgrade-path) | | | | |
| JS/TS SDK v5 | Unsupported | ≥ 3.63.0 | Full | GA |
| JS/TS SDK v4 | Unsupported | ≥ 3.63.0 | Deprecated | Deprecated |
| JS/TS SDK v3 / v2 | Full | Full | Unsupported | Deprecated |
| JS/TS SDK v1 | Full | Unsupported | Unsupported | End of life |
| **Third-party instrumentation** · [OpenTelemetry docs](/integrations/native/opentelemetry) | | | | |
| OpenTelemetry
`/api/public/otel/v1/traces` | Unsupported | ≥ 3.22.0 | Full | GA |
| Direct scores ingestion
`/api/public/scores` | Full | Full | Full | GA |
| SDK scores ingestion
`score-create` via `/api/public/ingestion` | Full | Full | Full | GA |
| Legacy trace and observation events
`/api/public/ingestion` | Full | Full | Unsupported | Deprecated |
| **Read APIs** · [Public API docs](/docs/api-and-data-platform/features/public-api) | | | | |
| Observations API v2 & Metrics API v2
`/api/public/v2/...` | Unsupported | Unsupported | Full | GA |
| Scores API v3
`/api/public/v3/scores` | Unsupported | Full | Full | GA |
| Deprecated read APIs
`traces, observations, sessions, scores, metrics, dataset runs` | Full | Full | Unsupported | Deprecated |
| **Metrics & alerts** · [Alerts docs](/docs/observability/features/alerts) | | | | |
| [Alerts](/docs/observability/features/alerts) | Unsupported | Unsupported | Full | GA |
| **Integrations & exports** · [Export docs](/docs/api-and-data-platform/features/export-to-blob-storage) | | | | |
| [Blob storage export](/docs/api-and-data-platform/features/export-to-blob-storage) | Unsupported | Traces & observations | Enriched observations | GA |
| [PostHog integration](/integrations/analytics/posthog) | Unsupported | Traces & observations | Enriched observations | GA |
| [Mixpanel integration](/integrations/analytics/mixpanel) | Unsupported | Traces & observations | Enriched observations | GA |
| Legacy export source (traces and observations) | Unsupported | Full | Deprecated | Deprecated |
| **Evaluations** · [LLM-as-a-judge docs](/docs/evaluation/evaluation-methods/llm-as-a-judge) | | | | |
| Observation-level evaluators | Unsupported | ≥ 3.153.0 | Full | GA |
| Trace-level evaluators | Full | Full | Deprecated | Deprecated |
GA. Requires self-hosted server ≥ [3.63.0](https://github.com/langfuse/langfuse/releases/tag/v3.63.0); OSS v2 and older are unsupported.
**Limitations:**
| Capability | OSS v3 | OSS v4 |
| ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- |
| Tracing (OpenTelemetry) | Supported | Supported (real time with SDK ≥ 4.7.0) |
| Public API & querying (`api.*`) | Use the [legacy APIs](/docs/api-and-data-platform/features/public-api#access-via-sdks) `api.legacy.observations_v1` / `api.legacy.metrics_v1` | Supported (deprecated read APIs are removed on v4) |
Deprecated. Requires self-hosted server ≥ [3.63.0](https://github.com/langfuse/langfuse/releases/tag/v3.63.0); OSS v2 and older are unsupported.
**Limitations:**
| Capability | OSS v3 | OSS v4 |
| ------------------------------- | ------------------------------------------------- | ------------------------------------------------------------------------------ |
| Tracing (OpenTelemetry) | Supported | Supported (data delayed up to 15 min; Python SDK v4 ≥ 4.7.0 for real time) |
| Datasets & experiments | Datasets only (experiments require Python SDK v4) | Datasets only (experiments require Python SDK v4) |
| Public API & querying (`api.*`) | Supported | Unsupported (deprecated read APIs are removed on v4; upgrade to Python SDK v4) |
Deprecated.
**Limitations:**
| Capability | OSS v2 | OSS v3 | OSS v4 |
| -------------------------------- | ------------------------------------------------- | ------------------------------------------------- | ------------------------------------------------------------------------------ |
| Tracing (legacy batch ingestion) | Supported | Supported | Unsupported |
| Datasets & experiments | Datasets only (experiments require Python SDK v4) | Datasets only (experiments require Python SDK v4) | Datasets only (experiments require Python SDK v4) |
| Media (multimodal) | Requires OSS v3 | Supported | Supported |
| Public API & querying (`api.*`) | Supported | Supported | Unsupported (deprecated read APIs are removed on v4; upgrade to Python SDK v4) |
GA. Requires self-hosted server ≥ [3.63.0](https://github.com/langfuse/langfuse/releases/tag/v3.63.0); OSS v2 and older are unsupported.
**Limitations:**
| Capability | OSS v3 | OSS v4 |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| Tracing (OpenTelemetry) | Supported | Supported (real time with SDK ≥ 5.4.0) |
| Public API & querying (`api.*`) | Use the [legacy APIs](/docs/api-and-data-platform/features/public-api#access-via-sdks) `api.legacy.observationsV1` / `api.legacy.metricsV1` | Supported (deprecated read APIs are removed on v4. Langfuse Cloud serves these endpoints until November 16, 2026 (2026-11-16); migrate to v4 before this date.) |
Deprecated. Requires self-hosted server ≥ [3.63.0](https://github.com/langfuse/langfuse/releases/tag/v3.63.0); OSS v2 and older are unsupported.
**Limitations:**
| Capability | OSS v3 | OSS v4 |
| ------------------------------- | ------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
| Tracing (OpenTelemetry) | Supported | Supported (data delayed up to 15 min; JS/TS SDK v5 ≥ 5.4.0 for real time) |
| Datasets & experiments | Datasets only (experiments require JS/TS SDK v5) | Datasets only (experiments require JS/TS SDK v5) |
| Public API & querying (`api.*`) | Supported | Unsupported (deprecated read APIs are removed on v4. Langfuse Cloud serves these endpoints until November 16, 2026 (2026-11-16); upgrade to JS/TS SDK v5) |
Deprecated.
**Limitations:**
| Capability | OSS v2 | OSS v3 | OSS v4 |
| -------------------------------- | ------------------------------------------------ | ------------------------------------------------ | ----------------------------------------------------------------------------- |
| Tracing (legacy batch ingestion) | Supported | Supported | Unsupported |
| Datasets & experiments | Datasets only (experiments require JS/TS SDK v5) | Datasets only (experiments require JS/TS SDK v5) | Datasets only (experiments require JS/TS SDK v5) |
| Media (multimodal) | Requires OSS v3 | Supported | Supported |
| Public API & querying (`api.*`) | Supported | Supported | Unsupported (deprecated read APIs are removed on v4; upgrade to JS/TS SDK v5) |
GA. Any OpenTelemetry SDK can export to the OTLP endpoint, available since OSS [3.22.0](https://github.com/langfuse/langfuse/releases/tag/v3.22.0). On Langfuse v4, send the `x-langfuse-ingestion-version: 4` header on your span exporter to see data in real time; without it, data can be delayed by up to 15 minutes. (Langfuse SDKs at Python ≥ 4.7.0 / JS ≥ 5.4.0 qualify for real time automatically; self-hosted deployments can set `LANGFUSE_MIGRATION_V4_NATIVE_OTEL_BEHAVIOUR=direct` to make all OTLP ingestion real time without the header.) See the [OpenTelemetry setup guide](/integrations/native/opentelemetry).
Deprecated. Trace, span, and generation events via the legacy batch ingestion API are not supported on the v4 data model: on Langfuse Cloud they keep working until November 16, 2026 (2026-11-16), on self-hosted Langfuse v4 in `events_only` mode they are rejected. The same applies to the older `POST /api/public/traces`, `/spans`, `/generations`, and `/events` endpoints. Migrate to [OpenTelemetry ingestion](/faq/all/deprecated-api-migration#ingestion).
Deprecated. Removed on Langfuse v4 and on Langfuse Cloud on November 16, 2026 (2026-11-16). The [migration guide](/faq/all/deprecated-api-migration) is the canonical per-endpoint mapping with parameter tables and before/after examples; it also documents the [deprecated endpoints](/faq/all/deprecated-api-migration#endpoints) themselves.
| Deprecated `GET` endpoints | Replacement |
| ----------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| `/api/public/observations`, `/api/public/observations/{id}` | [Observations API v2](/faq/all/deprecated-api-migration#observations) |
| `/api/public/traces`, `/api/public/traces/{id}` | [Observations API v2, filtered by `traceId`](/faq/all/deprecated-api-migration#traces) |
| `/api/public/sessions`, `/api/public/sessions/{id}` | [Observations API v2, filtered by `sessionId`](/faq/all/deprecated-api-migration#sessions) |
| `/api/public/scores`, `/api/public/v2/scores` (+ `/{id}`) | [Scores API v3](/faq/all/deprecated-api-migration#scores) |
| `/api/public/metrics`, `/api/public/metrics/daily` | [Metrics API v2](/faq/all/deprecated-api-migration#metrics) |
| `/api/public/datasets/{name}/runs` (+ `/{runName}`) | [Experiments API](/faq/all/deprecated-api-migration#dataset-runs) |
| `/api/public/dataset-run-items` | [Experiment Items API](/faq/all/deprecated-api-migration#dataset-runs) |
GA. Requires Langfuse v4. See the [Observations API v2](/docs/api-and-data-platform/features/observations-api#v2) and [Metrics API v2](/docs/metrics/features/metrics-api#v2) docs.
- **Via SDK:** these are the default resources in Python SDK v4 (`api.observations`, `api.metrics`) and JS/TS SDK v5 (`api.observations`, `api.metrics`). On OSS v3, the defaults fail; use `api.legacy.observations_v1` / `api.legacy.metrics_v1` (Python) or `api.legacy.observationsV1` / `api.legacy.metricsV1` (JS/TS).
- **Via REST:** `GET /api/public/v2/observations?fromStartTime={datetime}&toStartTime={datetime}` and `GET /api/public/v2/metrics?query={json}`.
- **Data freshness:** data from older SDKs (Python < 4.7.0, JS < 5.4.0) or OTel exporters without the `x-langfuse-ingestion-version: 4` header can appear on these APIs with up to a 10-minute delay. Upgrade to Python SDK ≥ 4.7.0 / JS SDK ≥ 5.4.0 (or set the header) for real-time data.
GA. Requires Langfuse v4. Threshold-based alerts on your LLM application metrics with notifications via Slack, webhooks, and GitHub Actions; self-hosted deployments have no alert limit. See the [alerts docs](/docs/observability/features/alerts).
Deprecated. Migrate to [observation-level evaluators](/faq/all/llm-as-a-judge-migration). Trace-level evaluators are not supported on the v4 data model; on Langfuse Cloud they keep running until November 16, 2026 (2026-11-16). On self-hosted Langfuse v4 in `events_only` mode, they will no longer produce results.
Deprecated. Exports built on the legacy "traces and observations" source are replaced by the enriched observations source (v4 data model). On Langfuse Cloud, projects created on or after 2026-05-20 cannot select legacy sources, new legacy export integrations cannot be created since 2026-06-22, and remaining legacy exports are switched to the enriched source automatically on November 16, 2026 (2026-11-16).
## Release Notes
Release notes are published on GitHub:
- [Langfuse Server](https://github.com/langfuse/langfuse/releases)
- [Langfuse Python SDK](https://github.com/langfuse/langfuse-python/releases)
- [Langfuse JS/TS SDK](https://github.com/langfuse/langfuse-js/releases)
You can watch the GitHub releases to get notified about new releases:
Also, you can subscribe to our mailing list to get notified about new releases and new major versions:
**[Langfuse OSS updates](/self-hosting/oss-newsletter)** — get an email when we ship important features and new releases for self-hosted (open source) Langfuse. Self-hosting updates only, no spam.
Subscribe to the Langfuse OSS newsletter at https://langfuse.com/self-hosting/oss-newsletter.
---
If you experience any issues when self-hosting Langfuse, please:
1. Check out [Troubleshooting & FAQ](/self-hosting/troubleshooting-and-faq) page.
2. Use [Ask AI](/ask-ai) to get instant answers to your questions.
3. Ask the maintainers on [GitHub Discussions](/gh-support).
4. Create a bug report or feature request on [GitHub](/issues).
Enterprise-grade support is available when self-hosting Langfuse. Learn more on
our [pricing page](/pricing-self-host).
---
## Agent Instructions
This page is part of the [Langfuse](https://langfuse.com) documentation, published as plain Markdown for AI agents. Every page is available as Markdown by appending `.md` to its URL, or by sending an `Accept: text/markdown` header. This page: `https://langfuse.com/self-hosting/upgrade/versioning.md`.
### Querying these docs
If the answer is not on this page, query the documentation instead of guessing:
- **Semantic search** across all Langfuse docs, returning an answer with the relevant pages and excerpts. Ask a specific, self-contained question:
```bash
curl -sG "https://langfuse.com/api/search-docs" --data-urlencode "query=How do I trace a LangGraph agent?"
```
- **Index of every page**: , with per-section indexes [llms-docs.txt](https://langfuse.com/llms-docs.txt), [llms-integrations.txt](https://langfuse.com/llms-integrations.txt), and [llms-self-hosting.txt](https://langfuse.com/llms-self-hosting.txt).
### Before writing Langfuse code
- **Install the [Langfuse Agent Skill](https://langfuse.com/docs/api-and-data-platform/features/agent-skill).** It encodes Langfuse's own best practices for instrumentation, prompt management, and evaluation, and materially improves results.
- **Read [What does a good trace look like?](https://langfuse.com/docs/observability/best-practices.md)** before instrumenting an application.
- **Verify endpoints, parameters, and response fields** against the [API reference](https://api.reference.langfuse.com) instead of inferring them from code examples.
- **Use the [Langfuse CLI](https://langfuse.com/docs/api-and-data-platform/features/cli)** (`npx langfuse-cli api `) to read or write traces, prompts, datasets, and scores from the terminal.
Found an error in these docs? Please open an issue at .