Reference an artifact version with aliases

Use aliases to reference a specific artifact version in W&B Registry. Aliases provide stable, human-readable labels for versions that are current, in production, or otherwise important. W&B automatically assigns aliases to each artifact you link with the same name. You can also create custom aliases and 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, it appears as a gray rectangle with a lock icon. Otherwise, the alias appears as an orange rectangle. Aliases aren’t shared across registries.

When to use an alias versus using a tagUse an alias to reference a specific artifact version. Each alias within a collection is unique. Only one artifact version can have a specific alias at a time.Use tags to organize and group artifact versions or collections based on a common theme. Multiple artifact versions and collections can share the same tag.

When you add an alias to an artifact version, you can optionally start a Registry automation to notify a Slack channel or trigger a webhook. If the automation calls a webhook that needs an access token or other sensitive value in the request, store those strings as team secrets and select them when you configure the webhook for the automation.

Default aliases

W&B automatically assigns the following aliases to each artifact version you link with the same name:

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.

For example, if you link an artifact named zoo_model three times, W&B creates three aliases v0, v1, and v2 respectively. v2 also has the latest alias.

Custom aliases

Use custom aliases to label artifact versions by workflow, dataset, performance, or other criteria. 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 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 can’t add or remove aliases.

Protected aliases provide a way to label and identify which artifact versions to protect from modification or deletion.

You can create a custom alias with the W&B Registry or the Python SDK. Click the tab that fits your workflow.

W&B Registry
Python SDK

Navigate to the W&B Registry.
Click the View details button in a collection.
Within the Versions section, click the View button for a specific artifact version.
Click the + button to add one or more aliases next to the Aliases field.

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(). W&B creates an alias (non protected alias) 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 the bracketed placeholders with your own values:

import wandb

# Initialize a 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]")

    # 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]")

    # Specify the collection and registry to link the artifact to
    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]"]
        )

Protected aliases

Use a protected alias to identify an artifact version and prevent it from being modified or deleted. Protected aliases are useful for versions that downstream systems depend on. For example, use a production protected alias for artifact versions used in your organization’s production ML pipeline. Registry admin users and service accounts 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 for details. Common protected aliases include:

Production: The artifact version is ready for production use.
Staging: The artifact version is ready for testing.

Create a protected alias

The following steps describe how to create a protected alias in the W&B Registry UI:

Navigate to the W&B Registry.
Select a registry.
Click the gear button on the top right of the page to view the registry’s settings.
Within the Protected Aliases section, click the + button to add one or more protected aliases.

After creation, each protected alias appears as a gray rectangle with a lock icon in the Protected Aliases section.

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.

The following steps describe how to add a protected alias to an artifact version with the W&B Registry UI:

Navigate to the W&B Registry.
Click the View details button in a collection.
Within the Versions section, select the View button for a specific artifact version.
Click the + button to add one or more protected aliases next to the Aliases field.

After an admin creates a protected alias, it can be added to an artifact version either in the UI or programmatically with the Python SDK. See Custom aliases.

Find existing aliases

You can find aliases with the global search bar in the W&B Registry. To find a protected alias:

Navigate to the W&B Registry.
Specify the search term in the search bar at the top of the page. Press Enter to search.

Search results appear below the search bar if the term you specify matches an existing registry, collection name, artifact version tag, collection tag, or alias.

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.

The following code example is a continuation of this W&B Registry Tutorial notebook. To use the following code, you must first retrieve and process the Zoo dataset as described in the notebook. Once you have the Zoo dataset, you can create an artifact version and add custom aliases to it.

The following code snippet shows how to create an artifact version and add custom aliases to it. The example uses the Zoo dataset from the UCI Machine Learning Repository and the Model collection in the Zoo_Classifier_Models registry.

import wandb

# Initialize a run
with wandb.init(entity = "smle-reg-team-2", project = "zoo_experiment") 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 = "zoo_dataset", type = "dataset")

    # Add the file to the artifact object. 
    # Specify the path to the file on your local machine.
    artifact.add_file(local_path="zoo_dataset.pt", name="zoo_dataset")
    artifact.add_file(local_path="zoo_labels.pt", name="zoo_labels")

    # Specify the collection and registry to link the artifact to
    REGISTRY_NAME = "Model"
    COLLECTION_NAME = "Zoo_Classifier_Models"
    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 = ["production-us", "production-eu"]
        )

First, you create an artifact object (wandb.Artifact()).
Next, you add two dataset PyTorch tensors to the artifact object with wandb.Artifact.add_file().
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.

Guides

Integrations

Reference

Default aliases

Custom aliases

Protected aliases

Create a protected alias

Find existing aliases

Example

​Default aliases

​Custom aliases

​Protected aliases

​Create a protected alias

​Find existing aliases

​Example

Default aliases

Custom aliases

Protected aliases

Create a protected alias

Find existing aliases

Example