Skip to main content
After creating and publishing prompts, you can reference, retrieve, and use specific versions in code and in production. When you publish a prompt with weave.publish, W&B Weave creates an immutable version. You can reference each version by name and version, retrieve it in code with weave.ref(...).get(), and view it in the Weave UI.

​
Prompt versions

Weave stores prompts as versioned objects. This lets you safely iterate on prompts while ensuring that evaluations, experiments, and production systems can reference the exact prompt version they ran with. You access prompt versions using Weave object references. This page explains how Weave creates prompt versions, how to retrieve a specific version in code, and how to inspect and compare versions in the Weave UI.

​
How prompt versions are created

Weave automatically tracks every version of your prompts, creating a complete history of how your prompts evolve. This versioning system is important for prompt engineering workflows. It lets you experiment safely, track what changes improved or hurt performance, and roll back to previous versions if needed. Each time you publish a prompt with the same name but different content, Weave creates a new version while preserving all previous versions. Each version is immutable. Once created, the contents of that version cannot be changed. If you update a prompt and publish it again, Weave creates a new version while preserving previous versions. Versioning enables you to:
  • Reproduce past experiments.
  • Safely iterate on prompt changes.
  • Roll out prompt updates in a controlled way.

​
Construct a fully qualified ref URI

Before retrieving a prompt version in code, it helps to understand how Weave identifies stored objects. A fully qualified ref URI uniquely identifies a Weave object. A fully qualified Weave object ref URI looks like this: 
weave:///<your-team-name>/<your-project-name>/object/<object_name>:<object_version>
  • your-team-name: W&B entity (username or team name)
  • your-project-name: W&B project
  • object_name: object name
  • object_version: either a version hash, a version index like v0 or v1, or an alias like :latest or :production. All objects have the :latest alias.
For example, a fully qualified Weave prompt URI looks like this: 
weave:///your-team-name/your-project-name/object/support_prompt:v3

​
Retrieve a prompt version in code

To retrieve a prompt, create a reference to its name and version, then call .get() to load it. A ref points to a stored object; .get() fetches that object so you can use it in your application. You can construct refs with a few different styles:
  • weave.ref(<name>): Retrieves the :latest version of a prompt. Requires calling weave.init(...).
  • weave.ref(<name>:<alias_or_version>): Retrieves a prompt by alias, version hash, or version index. Requires calling weave.init(...).
  • weave.ref(<fully_qualified_ref_uri>): Retrieves the prompt located at the specified fully qualified ref URI. Does not require calling weave.init(...).
The following example loads the support_prompt:v3 version so you can use it in your application: 
import weave

weave.init("your-team-name/your-project-name")

prompt = weave.ref("support_prompt:v3").get()

​
Use prompts in production

When deploying prompts in production systems, use an alias like production rather than a version index or the latest version. In your production application, load the prompt with weave.ref(<name>:<alias>).get(). Using an alias keeps production behavior stable and predictable. When you’re ready to promote a new version, move the alias to that version. All consumers then automatically pick up the change. A common workflow looks like this:
  1. Develop and test a new prompt version.
  2. Evaluate the new prompt against datasets or evaluation suites.
  3. Move the production alias to the new version with client.set_aliases(new_ref, "production").
This approach lets teams safely iterate on prompts without unexpectedly changing production behavior.

​
View and compare prompt versions

The Weave UI lets you browse all versions of a prompt and view side-by-side diffs between them, which is useful for reviewing how a prompt has evolved. To view versions of the prompt in the UI:
  1. Navigate to wandb.ai and select your project.
  2. In the Weave project sidebar, click Assets. This opens the Assets page.
  3. In the Assets page, click Prompts. This opens the Prompts page where your project’s prompts are listed.
  4. Under the Versions column, click (x) Versions for the prompt you want to view. This opens a list of prompt versions.
UI of Prompt Assets, showing the versions of the selected prompt.
  1. (Optional) To compare versions of prompts, click the checkboxes beside the listed prompts and then click the Compare button in the table toolbar. This lets you see the diff between your prompts.
The Compare prompts UI showing a diff between two different prompt versions.

​
Add prompt tags and aliases

You can organize prompt versions using aliases and tags. These labels help you identify and reference specific versions across development, evaluation, and production workflows.
  • Alias: A unique name that resolves to a single prompt version. You can move an alias to point to a different version at any time, making it useful for stable references like production or staging.
  • Tag: A descriptive label you attach to a version. A version can have multiple tags. Use tags to categorize and filter versions, such as reviewed or passed-eval.
To set aliases and tags for your prompts in the UI:
  1. In the Weave project sidebar, click Assets. This opens the Assets page.
  2. In the Assets page, click Prompts. Note that you can view assigned Aliases and Tags in the table.
  3. In the Prompts table, click the link of the prompt you want to change.
  4. In the prompt detail panel for your selected prompt, the title bar displays the name of the prompt and a specific version. Choose the version of the prompt you want to update.
  5. In the panel toolbar, use the controls to add and remove assigned aliases and tags to this specific version.
A selected prompt version in the prompt detail panel on the Prompts page, showing controls for Aliases and Tags.

​
Modify tags and aliases in code

You can also manage tags and aliases in code, for tasks such as:
  • Publishing prompts with tags and aliases inline.
  • Pointing aliases at specific versions and resolving them to load prompts.
  • Adding, removing, or listing tags and aliases on versions.
The following code example adds a prompt my-prompt to your project with three versions, each having various tags and aliases. Update 'your-team-name/your-project-name' accordingly for your project. 
import weave

// TODO: Set 'your-team-name/your-project-name' to correct values.
client = weave.init('your-team-name/your-project-name')

# Publish two versions of a prompt.
v0_ref = weave.publish(
    weave.StringPrompt("Answer the user's question: {question}"),
    name="my-prompt",
)
v1_ref = weave.publish(
    weave.StringPrompt("Answer the user's question helpfully and concisely: {question}"),
    name="my-prompt",
)

# --- Aliases: named pointers to a specific version. ---

# Point aliases at a version.
client.set_aliases(v0_ref, "staging")
client.set_aliases(v1_ref, "production")

# Retrieve aliases for a version.
client.get_aliases(v1_ref)  # ["production", "latest"]

# Move an alias by setting it on a different version.
client.set_aliases(v0_ref, "production")  # Automatically detaches from v1.

# Resolve an alias to load the object.
prompt = weave.ref("my-prompt:production").get()

# List all aliases in the project.
client.list_aliases()

# Remove an alias.
client.remove_aliases(v0_ref, "production")

# --- Tags: labels on a specific version. ---

# Add tags to a version.
client.add_tags(v0_ref, ["reviewed", "passed-eval"])
client.add_tags(v1_ref, ["reviewed", "needs-improvement"])

# Get tags for a version.
client.get_tags(v0_ref)  # ["passed-eval", "reviewed"]

# List all distinct tags in the project.
client.list_tags()

# Remove tags from a version.
client.remove_tags(v1_ref, ["needs-improvement"])

# --- Combined: fetch both in a single call. ---

tags, aliases = client.get_tags_and_aliases(v0_ref)

# --- Publish with tags and aliases inline. ---

ref = weave.publish(
    weave.StringPrompt("Be brief: {question}"),
    name="my-prompt",
    tags=["reviewed"],
    aliases=["production"],
)
When you run the example, Weave prints links to your objects in the Weave dashboard. Follow the links to see your prompts.