Skip to main content

Link an artifact version to a registry

Programmatically or interactively link artifact versions to a registry.

W&B recommends that you check the artifact types that the registry permits. Each registry controls the types of artifacts that can be linked to that registry.

info

The term "type" refers to the artifact object type. When you create an artifact object (wandb.Artifact), or log an artifact (wandb.run.log_artifact), you specify a type for the type parameter.

As an example, by default, the Model registry only permits artifacts objects that have a "model" type. W&B will not permit you to link a dataset artifact type object if you try to link it to the Model registry.

info

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 linked artifact versions when you link an artifact to a collection.

In other words, linking an artifact to a registry collection brings that artifact version from a private, project-level scope, to the shared organization level scope.

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

Programmatically link an artifact version to a collection with link_artifact. Before you link an artifact to a collection, ensure that the registry that the collection belongs to already exists.

Use the target_path parameter to specify the collection and registry you want to link the artifact version to. The target path consists of:

{ORG_ENTITY_NAME}/wandb-registry-{REGISTRY_NAME}/{COLLECTION_NAME}

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:

import wandb

TEAM_ENTITY_NAME = "<team_entity_name>"
ORG_ENTITY_NAME = "<org_entity_name>"

REGISTRY_NAME = "<registry_name>"  
COLLECTION_NAME = "<collection_name>"

run = wandb.init(
        entity=TEAM_ENTITY_NAME, project="<project_name>")

artifact = wandb.Artifact(name="<artifact_name>", type="<collection_type>")
artifact.add_file(local_path="<local_path_to_artifact>")

target_path=f"{ORG_ENTITY_NAME}/wandb-registry-{REGISTRY_NAME}/{COLLECTION_NAME}"
run.link_artifact(artifact = artifact, target_path = target_path)

If you want to link an artifact version to the Models registry or the Dataset registry, set the artifact type to "model" or "dataset", respectively.

For example, the proceeding code snippet simulates logging a model artifact called "my_model.txt" to a collection called "Example ML Task" within the model registry:

import wandb

TEAM_ENTITY_NAME = "<team_entity_name>"
ORG_ENTITY_NAME = "<org_entity_name>"

REGISTRY_NAME = "model" 
COLLECTION_NAME = "Example ML Task"

COLLECTION_TYPE = "model"


with wandb.init(entity=TEAM_ENTITY_NAME, project="link_quickstart") as run:
  with open("my_model.txt", "w") as f:
    f.write("simulated model file")

  logged_artifact = run.log_artifact("./my_model.txt", "artifact-name", type=COLLECTION_TYPE)
  run.link_artifact(
    artifact=logged_artifact,
    target_path=f"{ORG_ENTITY_NAME}/wandb-registry-{REGISTRY_NAME}/{COLLECTION_NAME}"
  )

Troubleshooting​

Below are some common things to double check if you are not able to link an artifact.

Logging artifacts from a personal account​

Artifacts logged to W&B with a personal entity can not be linked to the registry. Make sure that you log artifacts using a team entity within your organization. Only artifacts logged within an organization's team can be linked to the organization's registry.

tip

Ensure that you you log an artifact with a team entity if you want to link that artifact to a registry.

Find your team entity​

W&B uses the name of your team as the team's entity. For example, if your team is called "team-awesome", your team entity is team-awesome.

You can confirm the name of your team by:

  1. Navigate to your team's W&B profile page.
  2. Copy the site's URL. It has the form of https://wandb.ai/<team>. Where <team> is the both the name of your team and the team's entity.

Log from a team entity​

  1. Specify the team as the entity when you initialize a run with wandb.init(). If you do not specify the entity when you initialize a run, the run uses your default entity which may or may not be your team entity.
import wandb   

run = wandb.init(
  entity='<team_entity_name>', 
  project='<project_name>'
  )

  1. Log the artifact to the run either with run.log_artifact or by creating an Artifact object and then adding files to it with :

    artifact = wandb.Artifact(name="<artifact_name>", type="<collection_type>")
    run.log_artifact(artifact)

    For more information on how to log artifacts, see Construct artifacts.

  2. If an artifact is logged to your personal entity, you will need to re-log it to an entity within your organization.

Organization names with team name collisions​

W&B appends a unique hash to the organization name to avoid naming collisions with existing entities. The combination of the name and the unique hash is known as an organizational identifier or ORG_ENTITY_NAME.

For example, if your organization name is "reviewco" and you also have a team named "reviewco", W&B appends a hash to the organization name that results in an ORG_ENTITY_NAME named reviewco_XYZ123456.

tip

When linking to a registry with the Python SDK, always use the ORG_ENTITY_NAME format in the target_path.

For example, the target path might look like reviewco_XYZ123456/wandb-registry-model/my-collection.

Confirm the path of a registry in the W&B App UI​

There are two ways to confirm the path of a registry with the UI: create an empty collection and view the collection details or copy and paste the autogenerated code on the collection's home page.

Copy and paste autogenerated code​

  1. Navigate to the Registry app at https://wandb.ai/registry/.
  2. Click the registry you want to link an artifact to.
  3. At the top of the page, you will see an autogenerated code block.
  4. Copy and paste this into your code, ensure to replace the last part of the path with the name of your collection.

Create an empty collection​

  1. Navigate to the Registry app at https://wandb.ai/registry/.
  2. Click the registry you want to link an artifact to.
  3. Click on the empty collection. If an empty collection does not exist, create a new collection.
  4. Within the code snippet that appears, identify the target_path field within run.link_artifact().
  5. (Optional) Delete the collection.

For example, after completing the steps outlined, you find the code block with the target_path parameter:

target_path = 
      "smle-registries-bug-bash/wandb-registry-Golden Datasets/raw_images"

Breaking this down into its components, you can see what you will need to use to create the path to link your artifact programmatically:

ORG_ENTITY_NAME = "smle-registries-bug-bash"
REGISTRY_NAME = "Golden Datasets"
COLLECTION_NAME = "raw_images"
note

Ensure that you replace the name of the collection from the temporary collection with the name of the collection that you want to link your artifact to.

On this page
Was this page helpful?👍👎