> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wandb.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Link an artifact version to a collection

> Link an artifact version to a collection in W&B Registry to share it across your organization.

To make an artifact version available to your organization, *link* it to a [collection](/models/registry/create_collection) in
the W\&B Registry. Linking moves the version from a [private, project-level scope to a shared, organization-level scope](/models/registry/create_registry#visibility-types). You
can link an artifact version [programmatically by using the W\&B Python SDK or interactively in the W\&B App](/models/registry/link_version#link-an-artifact-to-a-collection).

When you link an artifact, W\&B creates a reference between the source artifact and the collection entry. The linked version points to the source artifact version that was 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.

## Link an artifact to a collection

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

<Note>
  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](./create_collection).
  * The registry that the collection belongs to already exists. To check that the registry exists, navigate to the [Registry App and search for](/models/registry/search_registry) the name of the registry.
</Note>

<Tabs>
  <Tab title="Python SDK">
    {/* <Note>
        Watch a [video demonstrating linking a version](https://www.youtube.com/watch?v=2i_n1ExgO0A) (8 min).
        </Note> */}

    Programmatically link an artifact version to a collection with [`wandb.Run.link_artifact()`](/models/ref/python/experiments/run#link_artifact) or
    [`wandb.Artifact.link()`](/models/ref/python/experiments/artifact#method-artifactlink).

    <Note>
      Use `wandb.Run.link_artifact()` to link an artifact version [within the context of a run](#link-an-artifact-version-within-the-context-of-a-run). Use `wandb.Artifact.link()` to link an *existing artifact version* [outside the context of a run](#link-an-artifact-version-outside-the-context-of-a-run).
    </Note>

    {/* <Note>
        `wandb.Artifact.link()` does not require you to initialize a run with `wandb.init()`. `wandb.Run.link_artifact()` requires you to initialize a run with `wandb.init()`.
        </Note> */}

    For both approaches, specify the name of the artifact (`wandb.Artifact(name="<name>"`), the type  of artifact (`wandb.Artifact(type="<type>"`), and the `target_path` (`wandb.Artifact(target_path="<target_path>"`)) of 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:

    {/* 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: */}

    ```text theme={null}
    wandb-registry-{REGISTRY_NAME}/{COLLECTION_NAME}
    ```

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

    Use `wandb.Run.link_artifact()` to link an artifact version within the context of a run. To do so,
    first initialize a run with `wandb.init()`. Next, create an artifact object and add files to it. Finally, use the `wandb.Run.link_artifact()` method to link the artifact version to the collection.

    When you use this approach, a run is created in your W\&B project. The artifact version is linked to the collection and is associated with that run.

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

    ```python theme={null}
    import wandb

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

    # Initialize a run
    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)
    ```

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

    Use `wandb.Artifact.link()` to link an existing artifact version outside the context of a run. With this approach,
    you do not need to initialize a run with `wandb.init()`. This means that a run is not created in your W\&B project. In other
    words, the artifact version is linked to the collection without being associated with a run.

    First, create an artifact object and add files to it. Next, use the `wandb.Artifact.link()` method to link the artifact version to the collection.

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

    ```python theme={null}
    import wandb

    # 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
    artifact.link(target_path = target_path)
    ```
  </Tab>

  <Tab title="W&B Registry">
    1. Navigate to the W\&B Registry.
           <Frame>
             <img src="https://mintcdn.com/wb-21fd5541/uqPGOvf46GQ1vVUB/images/registry/navigate_to_registry_app.png?fit=max&auto=format&n=uqPGOvf46GQ1vVUB&q=85&s=75847a775b0ae785bd19b17e3389c66e" alt="W&B Registry UI with project sidebar" width="2970" height="1920" data-path="images/registry/navigate_to_registry_app.png" />
           </Frame>
    2. Hover your mouse next to the name of the collection you want to link an artifact version to.
    3. Select the **action (<Icon icon="ellipsis" iconType="solid" />)** menu next to **View details**.
    4. From the dropdown, select **Link new version**.
    5. From the sidebar that appears, select the name of a team from the **Team** dropdown.
    6. From the **Project** dropdown, select the name of the project that contains your artifact.
    7. From the **Artifact** dropdown, select the name of the artifact.
    8. From the **Version** dropdown, select the artifact version you want to link to the collection.

    {/* TO DO insert gif */}
  </Tab>

  <Tab title="Artifact browser">
    1. Navigate to your project's artifact browser on the W\&B App at: `https://wandb.ai/<entity>/<project>/artifacts`
    2. Select the Artifacts icon in the project sidebar.
    3. Click on the artifact version you want to link to your registry.
    4. Within the **Version overview** section, click the **Link to registry** button.
    5. From the modal that appears on the right of the screen, select an artifact from the **Select a register model** menu dropdown.
    6. Click **Next step**.
    7. (Optional) Select an alias from the **Aliases** dropdown.
    8. Click **Link to registry**.

    {/* Update this gif */}

    {/* <Frame>
          <img src="/images/models/manual_linking.gif"  />
        </Frame> */}
  </Tab>
</Tabs>

You can [view a linked artifact's metadata, version data, usage, lineage information](/models/registry/link_version#view-linked-artifacts-in-a-registry") and more in the Registry App.

## View linked artifacts in a registry

View information about linked artifacts such as metadata, lineage, and usage information in the W\&B Registry.

1. Navigate to the W\&B Registry.
2. Select the name of the registry that you linked the artifact to.
3. Select the name of the collection.
4. If the collection's artifacts log metrics, compare metrics across versions by clicking **Show metrics**.
5. From the list of artifact versions, select the version you want to access. Version numbers are incrementally assigned to each linked artifact version starting with `v0`.
6. To view details about an artifact version, click the version. From the tabs in this page, you can view that version's metadata (including logged metrics), lineage, and usage information.

Make note of the **Full Name** field within the **Version** tab. The full name of a linked artifact consists of the registry, collection name, and the alias or index of the artifact version.

```text title="Full name of a linked artifact" theme={null}
wandb-registry-{REGISTRY_NAME}/{COLLECTION_NAME}:v{INTEGER}
```

You need the full name of a linked artifact to access the artifact version programmatically.

## 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.

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

#### 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()`](/models/ref/python/functions/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.

   ```python theme={null}
   import wandb   

   with wandb.init(entity='<team_entity>', project='<project_name>') as run:
       # Log your artifact here
   ```

2. Log the artifact to the run either with `wandb.Run.log_artifact()` or by creating an Artifact object and then adding files to it with:

   ```python theme={null}
   artifact = wandb.Artifact(name="<artifact_name>", type="<type>")
   ```

   To log artifacts, see [Construct artifacts](/models/artifacts/construct-an-artifact/).

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

### 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 homepage.

#### Copy and paste autogenerated code

1. Navigate to the W\&B Registry at [https://wandb.ai/registry/](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.

<Frame>
  <img src="https://mintcdn.com/wb-21fd5541/mmuC1X8m1VKb0ElQ/images/registry/get_autogenerated_code.gif?s=f9d7b8780ca1624036bd8a2e7c8fb810" alt="Auto-generated code snippet" width="3718" height="2304" data-path="images/registry/get_autogenerated_code.gif" />
</Frame>

#### Create an empty collection

1. Navigate to the W\&B Registry at [https://wandb.ai/registry/](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 `.link_artifact()`.
5. (Optional) Delete the collection.

<Frame>
  <img src="https://mintcdn.com/wb-21fd5541/mmuC1X8m1VKb0ElQ/images/registry/check_empty_collection.gif?s=55657fd8dd288dea88008faeb8db6ea6" alt="Create an empty collection" width="3752" height="2190" data-path="images/registry/check_empty_collection.gif" />
</Frame>

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

```python theme={null}
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:

```python theme={null}
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.
</Note>