Manage artifact data retention

Set time-to-live (TTL) policies on W&B artifacts to schedule automatic deletion and manage storage consumption.

Schedule when W&B deletes artifacts with a W&B Artifact time-to-live (TTL) policy. Use TTL policies to automate cleanup of stale artifact data, manage storage consumption, and enforce data retention requirements without manually tracking which artifacts to remove. When you delete an artifact, W&B marks that artifact as a “soft-delete.” In other words, W&B marks the artifact for deletion but doesn’t immediately delete files from storage. For more information on how W&B deletes artifacts, see the Delete artifacts page.

Watch a Managing data retention with Artifacts TTL video tutorial to learn how to manage data retention with Artifacts TTL in the W&B App.

W&B deactivates the option to set a TTL policy for artifacts linked to the Registry. This helps ensure that linked artifacts don’t accidentally expire when used in production workflows.

• Only team admins can view a team’s settings and access team-level TTL settings such as (1) permitting who can set or edit a TTL policy or (2) setting a team default TTL.
• If you don’t see the option to set or edit a TTL policy in an artifact’s details in the W&B App UI, or if setting a TTL programmatically doesn’t change an artifact’s TTL property, your team admin hasn’t given you permissions to do so.

Autogenerated artifacts

Before you set a TTL policy, confirm that the target artifact is eligible. Only user-generated artifacts can use TTL policies. W&B-generated artifacts can’t have TTL policies set for them.

The following artifact types indicate an autogenerated artifact:

• run_table
• code
• job
• Any artifact type starting with wandb-*

You can check an artifact’s type on the W&B platform or programmatically:

import wandb

with wandb.init(project="[MY-PROJECT-NAME]") as run:
    artifact = run.use_artifact(artifact_or_name="[MY-ARTIFACT-NAME]")
    print(artifact.type)

Replace the bracketed placeholders with your own values.

Define who can edit and set TTL policies

Define who can set and edit TTL policies within a team to control which users can change artifact retention. Grant TTL permissions only to team admins, or grant both team admins and team members TTL permissions.

Only team admins can define who can set or edit a TTL policy.

1. Navigate to your team’s profile page.
2. Select the Settings tab.
3. Navigate to the Artifacts time-to-live (TTL) section.
4. From the TTL permissions dropdown, select who can set and edit TTL policies.
5. Click Review and save settings.
6. Confirm the changes and select Save settings.

Create a TTL policy

Set a TTL policy for an artifact either when you create the artifact or retroactively after you create the artifact. The following sections describe both approaches and additional options for setting team-wide defaults or working outside of a run.

For all the following code snippets, replace the bracketed placeholders with your own values to use the code snippet.

Set a TTL policy when you create an artifact

Use the W&B Python SDK to define a TTL policy when you create an artifact. You typically define TTL policies in days.

Defining a TTL policy when you create an artifact is similar to how you normally create an artifact, except that you pass in a time delta to the artifact’s ttl attribute.

The steps are as follows:

1. Create an artifact.
2. Add content to the artifact such as files, a directory, or a reference.
3. Define a TTL time limit with the datetime.timedelta data type that is part of Python’s standard library.
4. Log the artifact.

The following code snippet demonstrates how to create an artifact and set a TTL policy.

import wandb
from datetime import timedelta

with wandb.init(project="[MY-PROJECT-NAME]", entity="[MY-ENTITY]") as run:
    artifact = wandb.Artifact(name="[ARTIFACT-NAME]", type="[TYPE]")
    artifact.add_file("[MY-FILE]")

    artifact.ttl = timedelta(days=30)  # Set TTL policy
    run.log_artifact(artifact)

The preceding code snippet sets the TTL policy for the artifact to 30 days. In other words, W&B deletes the artifact after 30 days.

Set or edit a TTL policy after you create an artifact

Use the W&B App UI or the W&B Python SDK to define a TTL policy for an artifact that already exists.

When you modify an artifact’s TTL, W&B still calculates the expiration time using the artifact’s createdAt timestamp.

Python SDK

1. Fetch your artifact.
2. Pass in a time delta to the artifact’s ttl attribute.
3. Update the artifact with the save method.

The following code snippet shows how to set a TTL policy for an artifact:

import wandb
from datetime import timedelta

with wandb.init(project="[MY-PROJECT]") as run:
    artifact = run.use_artifact("[MY-ENTITY]/[MY-PROJECT]/[MY-ARTIFACT]:[ALIAS]")
    artifact.ttl = timedelta(days=365 * 2)  # Delete in two years
    artifact.save()

The preceding code example sets the TTL policy to two years.

W&B App

1. Navigate to your W&B project in the W&B App UI.
2. Select the artifact icon in the project sidebar.
3. From the list of artifacts, expand the artifact type that contains your artifact.
4. Select the artifact version you want to edit the TTL policy for.
5. Click the Version tab.
6. From the dropdown, select Edit TTL policy.
7. Within the modal that appears, select Custom from the TTL policy dropdown.
8. Within the TTL duration field, set the TTL policy in units of days.
9. Select the Update TTL button to save your changes.

Set default TTL policies for a team

Only team admins can set a default TTL policy for a team.

Set a default TTL policy for your team to apply a consistent retention period across artifacts without configuring each one individually. Default TTL policies apply to all existing and future artifacts based on their respective creation dates. The team’s default TTL doesn’t affect artifacts with existing version-level TTL policies.

1. Navigate to your team’s profile page.
2. Select the Settings tab.
3. Navigate to the Artifacts time-to-live (TTL) section.
4. Click the Set team’s default TTL policy.
5. Within the Duration field, set the TTL policy in units of days.
6. Click Review and save settings.
7. Confirm the changes and then select Save settings.

Set a TTL policy outside of a run

Use the public API to retrieve an artifact without fetching a run, and set the TTL policy. You typically define TTL policies in days.

The following code sample shows how to fetch an artifact using the public API and set the TTL policy.

import wandb
from datetime import timedelta

api = wandb.Api()

artifact = api.artifact("[ENTITY]/[PROJECT]/[ARTIFACT]:[ALIAS]")

artifact.ttl = timedelta(days=365)  # Delete in one year

artifact.save()

Deactivate a TTL policy

Use the W&B Python SDK or W&B App UI to deactivate a TTL policy for a specific artifact version when you no longer want the artifact to expire automatically.

Python SDK

1. Fetch your artifact.
2. Set the artifact’s ttl attribute to None.
3. Update the artifact with the save method.

The following code snippet shows how to deactivate a TTL policy for an artifact:

import wandb

with wandb.init(project="[MY-PROJECT]") as run:
    artifact = run.use_artifact("[MY-ENTITY]/[MY-PROJECT]/[MY-ARTIFACT]:[ALIAS]")
    artifact.ttl = None
    artifact.save()

W&B App

1. Navigate to your W&B project in the W&B App UI.
2. Select the artifact icon in the project sidebar.
3. From the list of artifacts, expand the artifact type that contains your artifact.
4. Select the artifact version you want to edit the TTL policy for.
5. Click the Version tab.
6. Click the action () menu next to the Link to registry button.
7. From the dropdown, select Edit TTL policy.
8. Within the modal that appears, select Deactivate from the TTL policy dropdown.
9. Select the Update TTL button to save your changes.

View TTL policies

View TTL policies for artifacts with the Python SDK or with the W&B App UI to confirm the retention period applied to each artifact.

Python SDK

Use a print statement to view an artifact’s TTL policy. The following example shows how to retrieve an artifact and view its TTL policy:

import wandb

with wandb.init(project="[MY-PROJECT]") as run:
    artifact = run.use_artifact("[MY-ENTITY]/[MY-PROJECT]/[MY-ARTIFACT]:[ALIAS]")
    print(artifact.ttl)

W&B App

View a TTL policy for an artifact with the W&B App UI.

1. Navigate to the W&B App.
2. Navigate to your W&B Project.
3. Within your project, select the Artifacts tab in the project sidebar.
4. Click a collection.

Within the collection view you can see all of the artifacts in the selected collection. The Time to Live column shows the TTL policy assigned to each artifact.