> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://www.comet.com/docs/opik/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://www.comet.com/docs/opik/_mcp/server.

# Version control

Every change to a prompt in the Prompt Library creates a new immutable version, numbered
sequentially as `v1`, `v2`, `v3`, … Once created, a version can't be modified — you always have
a full audit trail.

You can create new versions from the Opik UI or from code using the SDK.

## Creating a new version

#### Opik UI

To create a new version from the Opik platform:

1. Navigate to the **Prompt Library** for your project
2. Open the prompt you want to edit
3. Click **Edit** and update the template
4. Click **Create new version**

The new version is available immediately.

#### Python SDK

Call `create_prompt` (or `create_chat_prompt`) again with the same `name` and the updated
template — the SDK creates the next sequential version automatically:

```python
import opik

client = opik.Opik()

# v1
client.create_prompt(
    name="system_prompt",
    prompt="You are a helpful assistant.",
    project_name="my-agent",
)

# v2
client.create_prompt(
    name="system_prompt",
    prompt="You are a coding assistant specializing in {{language}}.",
    project_name="my-agent",
)
```

If the template is identical to the latest version, no new version is created.

#### TypeScript SDK

Call `createPrompt` (or `createChatPrompt`) again with the same `name` and the updated
template — the SDK creates the next sequential version automatically:

```ts
import { Opik } from "opik";

const client = new Opik();

// v1
await client.createPrompt({
  name: "system_prompt",
  prompt: "You are a helpful assistant.",
  projectName: "my-agent",
});

// v2
await client.createPrompt({
  name: "system_prompt",
  prompt: "You are a coding assistant specializing in {{language}}.",
  projectName: "my-agent",
});
```

If the template is identical to the latest version, no new version is created.

## Fetching a specific version

Pass the `version` parameter to fetch a specific version, or omit it to fetch the most recent:

**`Python`**

```python title="Python"
import opik

client = opik.Opik()

# Fetch a specific version
v3 = client.get_prompt(name="system_prompt", version="v3", project_name="my-agent")

# Fetch the most recent version (omit `version`)
latest = client.get_prompt(name="system_prompt", project_name="my-agent")
```

**`TypeScript`**

```ts title="TypeScript"
import { Opik } from "opik";

const client = new Opik();

// Fetch a specific version
const v3 = await client.getPrompt({
  name: "system_prompt",
  version: "v3",
  projectName: "my-agent",
});

// Fetch the most recent version (omit `version`)
const latest = await client.getPrompt({
  name: "system_prompt",
  projectName: "my-agent",
});
```

## Comparing versions

You can compare any two versions side-by-side in the Opik UI to see exactly what changed. This is
useful for reviewing changes before pointing your agent at a new version.

![Version comparison view showing a diff of prompt changes between two versions](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/opik.docs.buildwithfern.com/58b75fbabe1f162e05e87ab9041465da51f2f3e0dc2b321179672fcd84dc5a20/img/v2/prompt-library/prompt-versions.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260921%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260921T085034Z&X-Amz-Expires=604800&X-Amz-Signature=c2b3df251f0b9ebaffd06863c7247a63d51609722b0f7613be57898e45ec3d21&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject)