Prompt Version Control

In Langfuse, version control & deployment of prompts is managed via versions and labels.

Implementation

Versions & Labels

Each prompt version is automatically assigned a version ID. Additionally, you can assign labels to follow your own versioning scheme.

Labels can be used to assign prompts to environments (staging, production), tenants (tenant-1, tenant-2), or experiments (prod-a, prod-b).

langfuse.create_prompt(
    name="movie-critic",
    type="text",
    prompt="As a {{criticlevel}} movie critic, do you like {{movie}}?",
    labels=["production"],  # add the label "production" to the prompt version
)

langfuse = Langfuse()
langfuse.update_prompt(
    name="movie-critic",
    version=1,
    new_labels=["john", "doe"], # assign these labels to the prompt version
)

import { LangfuseClient } from "@langfuse/client";

const langfuse = new LangfuseClient();

await langfuse.prompt.create({
  name: "movie-critic",
  type: "text",
  prompt: "As a {{criticlevel}} critic, do you like {{movie}}?",
  labels: ["production"], // add the label "production" to the prompt version
});

await langfuse.prompt.update({
  name: "movie-critic",
  version: 1,
  newLabels: ["john", "doe"],
});

Fetching by Label or Version

When fetching prompts to use them in your application you can either do so by fetching a specific version or label. Here are code examples for fetching prompts by label or version.

To "deploy" a prompt version, you have to assign the label production or any environment label you created to that prompt version.

Some notes on fetching prompts:

• The latest label points to the most recently created version.
• When using a prompt without specifying a label, Langfuse will serve the version with the production label.
• If no version carries the requested label, the request fails with 404 Not Found. Langfuse never silently falls back to production or latest; see how label resolution works.

from langfuse import get_client

# Initialize Langfuse client
langfuse = get_client()

# Get specific version
prompt = langfuse.get_prompt("movie-critic", version=1)

# Get specific label
prompt = langfuse.get_prompt("movie-critic", label="staging")

# Get latest prompt version. The 'latest' label is automatically maintained by Langfuse.
prompt = langfuse.get_prompt("movie-critic", label="latest")

import { LangfuseClient } from "@langfuse/client";

const langfuse = new LangfuseClient();

// Get specific version of a prompt (here version 1)
const prompt = await langfuse.prompt.get("movie-critic", {
  version: 1,
});

// Get specific label
const prompt = await langfuse.prompt.get("movie-critic", {
  label: "staging",
});

// Get latest prompt version. The 'latest' label is automatically maintained by Langfuse.
const prompt = await langfuse.prompt.get("movie-critic", {
  label: "latest",
});

How label resolution works

The SDKs fetch prompts from GET /api/public/v2/prompts/{name}, so these rules apply whether you call the API directly or use get_prompt / prompt.get:

Because a missing label is an error rather than a fallback, a typo in a label name or an environment whose label was never assigned surfaces immediately as a failed fetch, not as the wrong prompt being served. The SDKs handle this with a fallback prompt if you configure one; otherwise the error propagates to your code.

To check which labels exist without fetching a specific version, list prompts: GET /api/public/v2/prompts returns every prompt with its labels array, and GET /api/public/v2/prompts?label=staging returns only prompts that have a version carrying that label. Labels are also visible on the prompt's version table in the UI.

Operational workflows

Rollbacks

When a prompt has a production label, then that version will be served by default in the SDKs. You can quickly rollback to a previous version by setting the production label to that previous version in the Langfuse UI.

Prompt Diffs

The prompt version diff view shows you the changes you made to the prompt over time. This helps you understand how the prompt has evolved and what changes have been made to debug issues or understand the impact of changes.

Protected prompt labels

Protected prompt labels give project admins and owners (RBAC docs) the ability to prevent labels from being modified or deleted, ensuring better control over prompt deployment.

Once a label such as production is marked as protected:

• viewer and member roles cannot modify or delete the label from prompts, preventing changes to the production prompt version. This also blocks the deletion of the prompt.
• admin and owner roles can still modify or delete the label, effectively changing the production prompt version.

Admins and owners can update a label's protection status in the project settings.

Related Resources

• Prompts are scoped to a project — if you use separate projects for different environments, see how to sync prompts between them
• To compare prompt versions on a dataset before promoting a label, run Experiments.