Skip to content

style: apply /style-guide pass to models/registry #2721

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
johndmulhausen wants to merge 5 commits into
base: main
Choose a base branch
from
Open

style: apply /style-guide pass to models/registry #2721

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
07e5bdc
style: apply /style-guide pass to models/registry
johndmulhausen Jun 4, 2026
f1f7b2c
fix: address review feedback on registry style-guide pass
johndmulhausen Jun 5, 2026
3e4b220
style: back out keywords frontmatter from registry style-guide pass
johndmulhausen Jun 10, 2026
1856126
Merge origin/main into style-guide/models-reports-20260604-104120
johndmulhausen Jun 11, 2026
67aed69
Merge origin/main (#2764 image removal) into style branch
johndmulhausen Jun 15, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
44 changes: 24 additions & 20 deletions models/registry/aliases.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,9 +3,9 @@ title: Reference an artifact version with aliases
description: "Use default, custom, and protected aliases to reference specific artifact versions in W&B Registry."
---

Reference a specific [artifact version](/models/artifacts/create-a-new-artifact-version/) with one or more aliases. [W&B automatically assigns aliases](/models/registry/aliases/#default-aliases) to each artifact you link with the same name. You can also [create one or more custom aliases](/models/registry/aliases/#custom-aliases) to reference a specific artifact version.
Aliases give you a stable, human-readable way to point to a specific [artifact version](/models/artifacts/create-a-new-artifact-version/) in W&B Registry, so you can track which version is current, in production, or otherwise notable without having to remember version numbers. [W&B automatically assigns aliases](/models/registry/aliases/#default-aliases) to each artifact you link with the same name, and you can also [create one or more custom aliases](/models/registry/aliases/#custom-aliases) to reference a specific artifact version. This page explains the default aliases that W&B assigns automatically, how to create your own custom aliases, and how to use protected aliases to safeguard important versions.

Aliases appear as rectangles with the name of that alias in the rectangle in the Registry UI. If an [alias is protected](/models/registry/aliases/#protected-aliases), it appears as a gray rectangle with a lock icon. Otherwise, the alias appears as an orange rectangle. Aliases are not shared across registries.
Aliases appear as rectangles with the name of that alias in the rectangle in the Registry UI. If an [alias is protected](/models/registry/aliases/#protected-aliases), it appears as a gray rectangle with a lock icon. Otherwise, the alias appears as an orange rectangle. Aliases aren't shared across registries.

<Note>
**When to use an alias versus using a tag**
Expand All @@ -19,7 +19,7 @@ When you add an alias to an artifact version, you can optionally start a [Regist

## Default aliases

W&B automatically assigns the following aliases to each artifact version you link with the same name:
W&B automatically assigns the following aliases to each artifact version you link with the same name, so you can identify a version without configuring anything:

* The `latest` alias to the most recent artifact version you link to a collection.
* A unique version number. W&B counts each artifact version (zero indexing) you link. W&B uses the count number to assign a unique version number to that artifact.
Expand All @@ -28,19 +28,19 @@ For example, if you link an artifact named `zoo_model` three times, W&B creates

## Custom aliases

Create one or more custom aliases for a specific artifact versions based on your unique use case. For example:
Custom aliases let you label artifact versions with names that reflect your workflow, such as the dataset a model was trained on or which version is performing best. For example:

- You might use aliases such as `dataset_version_v0`, `dataset_version_v1`, and `dataset_version_v2` to identify which dataset a model was trained on.
- You might use a `best_model` alias to keep track of the best performing artifact model version.

Any user with a [**Member** or **Admin** registry role](/models/registry/configure_registry/#registry-roles) on a registry can add or remove a custom alias from a linked artifact in that registry. Users with the [**Restricted Viewer** or **Viewer** roles](/models/registry/configure_registry/#registry-roles) cannot add or remove aliases.
Any user with a [**Member** or **Admin** registry role](/models/registry/configure_registry/#role-permissions) on a registry can add or remove a custom alias from a linked artifact in that registry. Users with the [**Restricted Viewer** or **Viewer** roles](/models/registry/configure_registry/#role-permissions) can't add or remove aliases.

<Note>
[Protected aliases](/models/registry/aliases/#protected-aliases) provide a way to label and identify which artifact versions to protect from modification or deletion.
</Note>


You can create a custom alias with the W&B Registry or the Python SDK. Based on your use case, click on a tab below that best fits your needs.
You can create a custom alias with the W&B Registry or the Python SDK. Click the tab that fits your workflow.

<Tabs>
<Tab title="W&B Registry">
Expand All @@ -50,45 +50,46 @@ You can create a custom alias with the W&B Registry or the Python SDK. Based on
4. Click the **+** button to add one or more aliases next to the **Aliases** field.
</Tab>
<Tab title="Python SDK">
When you link an artifact version to a collection with the Python SDK you can optionally provide a list of one or more aliases as an argument to the `alias` parameter in [`link_artifact()`](/models/ref/python/experiments/run.md/#link_artifact). W&B creates an alias ([non protected alias](#custom-aliases)) for you if the alias you provide does not already exist.
When you link an artifact version to a collection with the Python SDK, you can optionally provide a list of one or more aliases as an argument to the `aliases` parameter in [`link_artifact()`](/models/ref/python/experiments/run/#method-runlink_artifact). W&B creates an alias ([non protected alias](#custom-aliases)) for you if the alias you provide doesn't already exist.

The following code snippet demonstrates how to link an artifact version to a collection and add aliases to that artifact version with the Python SDK. Replace values within `<>` with your own:
The following code snippet demonstrates how to link an artifact version to a collection and add aliases to that artifact version with the Python SDK. Replace the bracketed placeholders with your own values:

```python
import wandb

# Initialize a run
with wandb.init(entity = "<team_entity>", project = "<project_name>") as run:
with wandb.init(entity = "[TEAM-ENTITY]", project = "[PROJECT-NAME]") as run:

# Create an artifact object
# The type parameter specifies both the type of the
# artifact object and the collection type
artifact = wandb.Artifact(name = "<name>", type = "<type>")
artifact = wandb.Artifact(name = "[NAME]", type = "[TYPE]")

# Add the file to the artifact object.
# Specify the path to the file on your local machine.
artifact.add_file(local_path = "<local_path_to_artifact>")
artifact.add_file(local_path = "[LOCAL-PATH-TO-ARTIFACT]")

# Specify the collection and registry to link the artifact to
REGISTRY_NAME = "<registry_name>"
COLLECTION_NAME = "<collection_name>"
REGISTRY_NAME = "[REGISTRY-NAME]"
COLLECTION_NAME = "[COLLECTION-NAME]"
target_path=f"wandb-registry-{REGISTRY_NAME}/{COLLECTION_NAME}"

# Link the artifact version to the collection
# Add one or more aliases to this artifact version
run.link_artifact(
artifact = artifact,
target_path = target_path,
aliases = ["<alias_1>", "<alias_2>"]
aliases = ["[ALIAS-1]", "[ALIAS-2]"]
)
```
</Tab>
</Tabs>

### Protected aliases
Use a [protected alias](/models/registry/aliases/#protected-aliases) to both label and identify artifact versions that should not be modified or deleted. For example, consider using a `production` protected alias to label and identify artifact versions that are in used in your organization's machine learning production pipeline.

[Registry admin](/models/registry/configure_registry/#registry-roles) users and [service accounts](/support/models/articles/what-is-a-service-account-and-why-is-it-) with the **Admin** role can create protected aliases and add or remove protected aliases from an artifact version. Users and service accounts with **Member**, **Viewer**, and **Restricted Viewer** roles cannot unlink a protected version or delete a collection that contains a protected alias. See [Configure registry access](/models/registry/configure_registry/) for details.
Protected aliases combine labeling with a guardrail: besides identifying a version, they prevent that version from being modified or deleted, which is useful for releases that downstream systems depend on. For example, consider a `production` protected alias to label and identify artifact versions that are in use in your organization's machine learning production pipeline.

[Registry admin](/models/registry/configure_registry/#role-permissions) users and [service accounts](/support/models/articles/what-is-a-service-account-and-why-is-it-) with the **Admin** role can create protected aliases and add or remove protected aliases from an artifact version. Users and service accounts with **Member**, **Viewer**, and **Restricted Viewer** roles can't unlink a protected version or delete a collection that contains a protected alias. See [Configure registry access](/models/registry/configure_registry/) for details.

Common protected aliases include:

Expand All @@ -107,7 +108,7 @@ The following steps describe how to create a protected alias in the W&B Registry
After creation, each protected alias appears as a gray rectangle with a lock icon in the **Protected Aliases** section.

<Note>
Unlike custom aliases that are not protected, creating protected aliases is available exclusively in the W&B Registry UI and not programmatically with the Python SDK. To add a protected alias to an artifact version, you can use the W&B Registry UI or the Python SDK.
Unlike custom aliases that aren't protected, you can create protected aliases only in the W&B Registry UI, not programmatically with the Python SDK. To add a protected alias to an artifact version, you can use the W&B Registry UI or the Python SDK.
</Note>

The following steps describe how to add a protected alias to an artifact version with the W&B Registry UI:
Expand All @@ -117,10 +118,11 @@ The following steps describe how to add a protected alias to an artifact version
3. Within the **Versions** section, select the **View** button for a specific artifact version.
4. Click the **+** button to add one or more protected aliases next to the **Aliases** field.

After a protected alias is created, an admin can add it to an artifact version programmatically with the Python SDK. See the W&B Registry and Python SDK tabs in [Create a custom alias](#custom-aliases) section above for an example on how to add a protected alias to an artifact version.
After an admin creates a protected alias, the admin can add it to an artifact version programmatically with the Python SDK. For an example of how to add a protected alias to an artifact version, see [Custom aliases](#custom-aliases).

## Find existing aliases
You can find existing aliases with the [global search bar in the W&B Registry](/models/registry/search_registry/#search-for-registry-items). To find a protected alias:

Once you have aliases in place, you can find them with the [global search bar in the W&B Registry](/models/registry/search_registry/#search-for-registry-items). To find a protected alias:

1. Navigate to the W&B Registry.
2. Specify the search term in the search bar at the top of the page. Press Enter to search.
Expand All @@ -129,6 +131,8 @@ Search results appear below the search bar if the term you specify matches an ex

## Example

The following end-to-end example shows how to create an artifact, link it to a registry collection, and attach custom aliases in a single workflow.

<Note>
The following code example is a continuation of this [W&B Registry Tutorial notebook](https://colab.research.google.com/github/wandb/examples/blob/master/colabs/wandb_registry/zoo_wandb.ipynb). To use the following code, you must first [retrieve and process the Zoo dataset as described in the notebook](https://colab.research.google.com/github/wandb/examples/blob/master/colabs/wandb_registry/zoo_wandb.ipynb#scrollTo=87fecd29-8146-41e2-86fb-0bb4e3e3350a). Once you have the Zoo dataset, you can create an artifact version and add custom aliases to it.
</Note>
Expand Down Expand Up @@ -167,4 +171,4 @@ with wandb.init(entity = "smle-reg-team-2", project = "zoo_experiment") as run:

1. First, you create an artifact object (`wandb.Artifact()`).
2. Next, you add two dataset PyTorch tensors to the artifact object with `wandb.Artifact.add_file()`.
3. Lastly, you link the artifact version to the `Model` collection in the `Zoo_Classifier_Models` registry with `link_artifact()`. You also add two custom aliases to the artifact version by passing `production-us` and `production-eu` as arguments to the `aliases` parameter.
3. Finally, you link the artifact version to the `Model` collection in the `Zoo_Classifier_Models` registry with `link_artifact()`. You also add two custom aliases to the artifact version by passing `production-us` and `production-eu` as arguments to the `aliases` parameter.
Loading
Loading