Langfuse Python SDK: What the v4 Rewrite Changed and Who Should Migrate
🪢 Langfuse Python SDK - Instrument your LLM app with decorators or low-level SDK and get detailed tracing/observability. Works with any LLM or framework
At a glance
- What is it?
- The Langfuse Python SDK instruments LLM applications through OpenTelemetry-style spans and generations, plus datasets, evaluations, prompt management and a REST client. The v4 rewrite in March 2026 changed the API surface, so the first decision is whether your code is already on v4.
- Who is it for?
- Adopt langfuse-python if you want tracing, datasets, evaluations and prompt management behind one MIT-licensed client and you are starting fresh on v4. Do not adopt it if you only need spans in an existing OpenTelemetry pipeline, or if you are still pinned to v3 and cannot schedule the migration described in the v3 to v4 upgrade guide.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository received new commits within the last day.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The problem it solves: LLM calls that leave no usable record
An LLM application produces a stream of inputs, outputs, model names and latencies that a normal application log flattens into strings. The Langfuse Python SDK exists to turn those calls into structured observations that a backend can store, query and compare. The README describes the package as covering observability and tracing, datasets and experiments for offline evaluation and regression testing, LLM-as-a-judge and custom evaluations, prompt management, and a full REST API client. That is a wider scope than a tracer: the same client that records a generation can also attach a score to it or pull a prompt version.
The intended user is a Python engineer who owns an LLM feature and needs to answer questions like which prompt version produced this output, or did the change to the model regress the eval set. The README states the SDK works with any LLM or framework and ships OpenAI and LangChain integrations, so it is not tied to one provider. If your application is a single script that calls one model and prints the answer, the SDK is more machinery than the problem requires.
How tracing works: context managers, spans and generations
The mechanism is a context manager that opens an observation and closes it on exit. The README quickstart calls langfuse.start_as_current_observation(as_type="span", name="process-request") and binds the result to a span variable. Inside that block, a second call with as_type="generation" and a model argument creates a nested observation. The README notes that all spans are automatically closed when exiting their context blocks, which means the trace tree follows the shape of your Python with blocks rather than a manually managed parent identifier.
Updates are explicit. The span example calls span.update(output="Processing complete") and the generation example calls generation.update(output="Generated response"). So the SDK does not infer your payload from the call site; you tell it what the output was. The README describes the tracing layer as OpenTelemetry-based, which is the architectural detail that matters most for adoption: if your organisation already runs an OpenTelemetry collector, you are adding a second instrumentation path rather than extending the one you have. The README does not spell out the exporter configuration or how Langfuse spans map onto OTLP attributes, so that mapping is something to confirm against the SDK guide before you commit.
Getting it running: install, environment keys, one span
Installation is a single command: pip install langfuse. The quickstart lists three environment variables it reads: LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY and LANGFUSE_BASE_URL. The first two are credentials; the third points the client at a Langfuse instance, which matters because the SDK is not hardcoded to the hosted service.
The client is obtained through a factory function, get_client(), rather than a constructor call in the quickstart. After the tracing blocks, the README shows langfuse.flush() with the comment that it is for flushing events in short-lived applications. That is the operational detail most likely to bite: a script that exits without flushing may not deliver its events, and the README presents flush as the remedy rather than describing an automatic shutdown hook. For long-running services the flush call is not shown, but the SDK guide linked from the README is where the delivery behaviour is documented. The README also points to a machine-readable docs index at langfuse.com/llms.txt and a generated API reference at python.reference.langfuse.com, both of which are more current than the quickstart snippet.
The v4 rewrite is the real adoption cost
The README carries an important notice: the SDK was rewritten in v4 and released in March 2026, and readers are directed to a v3 to v4 upgrade guide. The quickstart code uses start_as_current_observation, which is a v4 API. Anyone with existing instrumentation written against v3 cannot copy the quickstart and expect it to run; the migration guide is a prerequisite, not an optional read.
The release cadence visible in the repository is another cost signal. Three releases landed in roughly two weeks in August and September 2026: v4.15.0 on 27 August, v4.15.1 on 28 August, and v4.15.2 on 9 September. Frequent patch releases are normal for an actively developed SDK, but they mean a pinned version is a deliberate choice rather than a default. The README does not describe a deprecation window or a compatibility shim for v3 call sites, so the size of the migration is something you measure against your own codebase using the upgrade guide rather than something the README quantifies. That absence is a genuine gap in the material.
Beyond tracing: datasets, evaluations and prompt management
The tracing API is the part with a code example, but the README's opening paragraph claims three more capabilities: datasets and experiments for offline evaluation and regression testing of prompt or model changes, including CI via a GitHub Actions experiment action; LLM-as-a-judge and custom evaluations expressed as scores; and prompt management. It also states the package includes a full REST API client.
None of these have a worked example in the README, which is a limitation of the documentation as presented here rather than of the SDK. The practical consequence is that the evaluation and prompt-management surfaces are the parts you should read in the SDK guide before assuming they fit your workflow. The CI angle is the most concrete claim: an experiment action that runs in GitHub Actions implies datasets can be executed headlessly, which is the difference between evaluation as a dashboard exercise and evaluation as a gate on a pull request. If that is what you need, verify the action's inputs and how it authenticates against your Langfuse instance, because the README does not show it.
Where it is the wrong tool
The clearest mismatch is an application that already has OpenTelemetry instrumentation and no interest in Langfuse's evaluation or prompt features. Adding this SDK puts a second tracing library in the process, and the README's OpenTelemetry-based description does not tell you whether the two can share a tracer provider cleanly. For that case, a plain OpenTelemetry setup with an OTLP exporter to whatever backend you already run is the smaller change, and the difference in approach is that you keep one instrumentation path and lose the dataset, score and prompt-management APIs.
A second mismatch is scope. If you only want to log prompts and completions for later reading, a logging handler or a database table will do, and the SDK's observation types, flush semantics and version churn are overhead you are not using. A third is timing: if you are mid-migration on v3, adopting v4 now means doing the migration and the adoption at once. The README gives no indication that v3 is still the recommended path, so this is a sequencing judgement rather than a documented recommendation.
Licence, maintenance and what to check before wiring it in
The package is MIT licensed, the same identifier the README badge points to. MIT permits commercial use and modification with the licence and copyright notice retained; that is the general shape of the licence, not legal advice, and if you redistribute the SDK inside a product you should read the licence text yourself. The licence covers this Python client. It does not describe the terms of the Langfuse server you point LANGFUSE_BASE_URL at, and the README does not discuss self-hosting versus the hosted service, so that is a separate question to settle.
Maintenance cost is dominated by the v4 rewrite and the release cadence. Every upgrade after v4 is a version bump plus whatever the release notes say; the rewrite itself is the one-off cost. The repository's last push date and the recent release list indicate active development, but the README does not state a support policy for older v4 minors. Before instrumenting a production service, confirm that your Langfuse deployment's version accepts the SDK version you install, since the README treats LANGFUSE_BASE_URL as a plain configuration value without describing compatibility rules. The smallest useful verification is the quickstart itself: one span, one generation, one flush, then check the UI.
Editorial conclusion
Adopt langfuse-python if you want tracing, datasets, evaluations and prompt management behind one MIT-licensed client and you are starting fresh on v4. Do not adopt it if you only need spans in an existing OpenTelemetry pipeline, or if you are still pinned to v3 and cannot schedule the migration described in the v3 to v4 upgrade guide. Before writing code, verify three things: your Langfuse deployment's base URL, whether that deployment accepts the v4 SDK, and that LANGFUSE_PUBLIC_KEY and LANGFUSE_SECRET_KEY are set in the environment the process actually reads. Then run the quickstart span once and confirm it appears in the UI before instrumenting the rest of the application.
Community notes