Skip to content

Registry: Edit "Link artifact to a collection" #1677

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
wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Registry: Edit "Link artifact to a collection" #1677

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
b342912
WIP
ngrayluna Sep 24, 2025
dc7442c
ready for tech review
ngrayluna Sep 24, 2025
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
111 changes: 81 additions & 30 deletions content/en/guides/core/registry/link_version.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,63 +3,113 @@ menu:
default:
identifier: link_version
parent: registry
title: Link an artifact version to a registry
title: Link an artifact version to a collection
weight: 5
---

Link artifact versions to a collection to make them available to other members in your organization.
Link an artifact version to a collection to make it available to other members in your organization. Linking an artifact to a collection brings that artifact version from a private, project-level scope, to a shared organization level scope.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Link an artifact version to a collection to make it available to other members in your organization. Linking an artifact to a collection brings that artifact version from a private, project-level scope, to a shared organization level scope.
Link an artifact version to a collection to make it available to other members in your organization. Linking an artifact to a collection brings that artifact version from a private project level scope, to a shared organization level scope.


When you link an artifact to a registry, this "publishes" that artifact to that registry. Any user that has access to that registry can access the linked artifact versions in the collection.
You can [link an artifact version to a collection]({{< relref "/guides/core/registry/link_version.md#link-an-artifact-version-to-a-collection" >}}) programmatically with the W&B Python SDK or interactively with the W&B App.

In other words, linking an artifact to a registry collection brings that artifact version from a private, project-level scope, to a shared organization level scope.
When you link an artifact version to a collection, W&B creates a linked version of that artifact in the collection. The linked version points to the source artifact version that is logged to a run within a project. You can view the linked version in the collection and the source version in the project where it was logged.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
When you link an artifact version to a collection, W&B creates a linked version of that artifact in the collection. The linked version points to the source artifact version that is logged to a run within a project. You can view the linked version in the collection and the source version in the project where it was logged.
When you link an artifact version to a collection, W&B creates a linked version of that artifact in the collection. The linked version points to the source artifact version that is logged to a run within a project. You can view both the linked version in the collection and the source version in the project where it was logged.


{{% alert %}}
<!-- {{% alert %}}
The term "type" refers to the artifact object's type. When you create an artifact object ([`wandb.Artifact`]({{< relref "/ref/python/experiments/artifact.md" >}})), or log an artifact ([`wandb.init.log_artifact`]({{< relref "/ref/python/experiments/run.md#log_artifact" >}})), you specify a type for the `type` parameter.
<!-- If you are familiar with Python, you can think of artifact types in W&B as having similar functions as Python data types. -->
{{% /alert %}} -->

{{% alert %}}
Watch a [video demonstrating linking a version](https://www.youtube.com/watch?v=2i_n1ExgO0A) (8 min).
{{% /alert %}}

## Link an artifact to a collection
## Link an artifact to a collection
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
## Link an artifact to a collection
## Link an artifact to a collection


Link an artifact version to a collection interactively or programmatically.
Based on your use case, follow the instructions described in the tabs below to link an artifact version.

{{% alert %}}
Before you link an artifact to a registry, check the types of artifacts that collection permits. For more information about collection types, see "Collection types" within [Create a collection]({{< relref "./create_collection.md" >}}).
Before you start, check the following:
* The types of artifacts that collection permits. For more information about collection types, see "Collection types" within [Create a collection]({{< relref "./create_collection.md" >}}).
* The registry that the collection belongs to already exists. To check that the registry exists, navigate to the [Registry App and search for]({{< relref "/guides/core/registry/search_registry" >}}) the name of the registry.
{{% /alert %}}

Based on your use case, follow the instructions described in the tabs below to link an artifact version.

{{% alert %}}

<!-- {{% alert %}}
If an artifact version logs metrics (such as by using `run.log_artifact()`), you can view metrics for that version from its details page, and you can compare metrics across artifact versions from the artifact's page. Refer to [View linked artifacts in a registry]({{< relref "#view-linked-artifacts-in-a-registry" >}}).
{{% /alert %}}
{{% /alert %}} -->



{{< tabpane text=true >}}
{{% tab header="Python SDK" %}}
{{% alert %}}
Watch a [video demonstrating linking a version](https://www.youtube.com/watch?v=2i_n1ExgO0A) (8 min).
{{% /alert %}}

Programmatically link an artifact version to a collection with [`wandb.init.Run.link_artifact()`]({{< relref "/ref/python/experiments/run.md#link_artifact" >}}).

Programmatically link an artifact version to a collection with [`wandb.init.Run.link_artifact()`]({{< relref "/ref/python/experiments/run.md#link_artifact" >}}) or [`wandb.Artifact.link()`]({{< relref "/ref/python/experiments/artifact.md#method-artifactlink" >}}). Use `wandb.init.Run.link_artifact()` if you are linking an artifact version [within the context of a run](#link-an-artifact-version-within-the-context-of-a-run). Use `wandb.Artifact.link()` if you are linking an artifact version [outside the context of a run](#link-an-artifact-version-outside-the-context-of-a-run).

{{% alert %}}
Before you link an artifact to a collection, ensure that the registry that the collection belongs to already exists. To check that the registry exists, navigate to the Registry app on the W&B App UI and search for the name of the registry.
`wandb.Artifact.link()` does not require you to initialize a run with `wandb.init()`. `wandb.init.Run.link_artifact()` requires you to initialize a run with `wandb.init()`.
{{% /alert %}}

Use the `target_path` parameter to specify the collection and registry you want to link the artifact version to. The target path consists of the prefix "wandb-registry", the name of the registry, and the name of the collection separated by a forward slashes:
For both approaches, specify the name of the artifact (`wandb.Artifact(type="<name>"`), the type of artifact (`wandb.Artifact(type="<type>"`), and the `target_path` of the collection and registry you want to link the artifact version to.
<!--
For both methods, specify the path of the collection and registry you want to link the artifact version to with the `target_path` parameter. -->

The target path consists of the prefix `"wandb-registry"`, the name of the registry, and the name of the collection separated by a forward slashes:

```text
wandb-registry-{REGISTRY_NAME}/{COLLECTION_NAME}
```
<br>

<!--
{{% alert %}}
If you want to link an artifact version to the Model registry or the Dataset registry, set the artifact type to `"model"` or `"dataset"`, respectively.
{{% /alert %}} -->

<br>

### Link an artifact version within the context of a run

Copy and paste the code snippet below to link an artifact version to a collection within an existing registry. Replace values enclosed in `<>` with your own:
When you use `wandb.init.Run.link_artifact()`, you need to initialize a run with `wandb.init()`. This means that a run is created in your W&B project.

Copy and paste the code snippet below. Replace values enclosed in `<>` with your own:

```python
import wandb

entity = "<team_entity>" # Your team entity
project = "<project_name>" # The name of the project that contains your artifact

# Initialize a run
run = wandb.init(
entity = "<team_entity>",
project = "<project_name>"
)
with wandb.init(entity = entity, project = project) 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 to the collection
run.link_artifact(artifact = artifact, target_path = target_path)
```

<br>

### Link an artifact version outside the context of a run

When you use `wandb.Artifact.link()`, you do not need to initialize a run with `wandb.init()`. This means that a run is not created in your W&B project. The artifact version is linked to the collection without being associated with a run.

Copy and paste the code snippet below. Replace values enclosed in `<>` with your own:

```python
import wandb

# Create an artifact object
# The type parameter specifies both the type of the
Expand All @@ -70,17 +120,18 @@ artifact = wandb.Artifact(name = "<name>", type = "<type>")
# Specify the path to the file on your local machine.
artifact.add_file(local_path = "<local_path_to_artifact>")

# Save the artifact
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit (non-blocking): Might be worth adding to this comment, that this save action will initialize a run

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@ibindlish Ahh noted. Follow up question:

Is is possible to link an artifact w/out creating a run (which is what Karan mentioned)? The Artifact.link() method requires either wandb.init() and/or Artifact.save(). (At least, when I was testing it out) 🤔

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If we add real details like this to a code block, maybe they should also be reflected in the narrative content in the page so they don't get lost.

artifact.save()

# 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 to the collection
run.link_artifact(artifact = artifact, target_path = target_path)
artifact.link(target_path = target_path)
```
{{% alert %}}
If you want to link an artifact version to the Model registry or the Dataset registry, set the artifact type to `"model"` or `"dataset"`, respectively.
{{% /alert %}}


{{% /tab %}}
{{% tab header="Registry App" %}}
Expand Down Expand Up @@ -116,10 +167,10 @@ If you want to link an artifact version to the Model registry or the Dataset reg
<!-- {{% alert title="Linked vs source artifact versions" %}}
* Source version: the artifact version inside a team's project that is logged to a [run]({{< relref "/guides/models/track/runs/" >}}).
* Linked version: the artifact version that is published to the registry. This is a pointer to the source artifact, and is the exact same artifact version, just made available in the scope of the registry.
{{% /alert %}}
-->
{{% /alert %}} -->


View a linked artifact's metadata, version data, usage, lineage information and more in the Registry App.
Once an artifact is linked, you can [view a linked artifact's metadata, version data, usage, lineage information]({{< relref "/guides/core/registry/link_version.md#view-linked-artifacts-in-a-registry" >}}) and more in the Registry App.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Once an artifact is linked, you can [view a linked artifact's metadata, version data, usage, lineage information]({{< relref "/guides/core/registry/link_version.md#view-linked-artifacts-in-a-registry" >}}) and more in the Registry App.
You can [view a linked artifact's metadata, version data, usage, lineage information]({{< relref "/guides/core/registry/link_version.md#view-linked-artifacts-in-a-registry" >}}) and more in the Registry App.

Nit, but I think the link text makes this clear.


## View linked artifacts in a registry

Expand Down