Python Library

• 1: agent
• 2: Artifact
• 3: controller
• 4: Data Types
• 4.1: Audio
• 4.2: BoundingBoxes2D
• 4.3: Graph
• 4.4: Histogram
• 4.5: Html
• 4.6: Image
• 4.7: ImageMask
• 4.8: Molecule
• 4.9: Object3D
• 4.10: Plotly
• 4.11: Table
• 4.12: Video
• 4.13: WBTraceTree
• 5: finish
• 6: Import & Export API
• 6.1: Api
• 6.2: File
• 6.3: Files
• 6.4: Job
• 6.5: Project
• 6.6: Projects
• 6.7: QueuedRun
• 6.8: Run
• 6.9: RunQueue
• 6.10: Runs
• 6.11: Sweep
• 7: init
• 8: Integrations
• 8.1: Integrations
• 8.2: Keras
• 8.2.1: keras
• 8.2.2: WandbCallback
• 8.2.3: WandbEvalCallback
• 8.2.4: WandbMetricsLogger
• 8.2.5: WandbModelCheckpoint
• 8.3: WandbTracer
• 9: launch-library
• 9.1: launch
• 9.2: launch_add
• 9.3: launch-library
• 9.4: LaunchAgent
• 10: log
• 11: login
• 12: Run
• 13: save
• 14: sweep
• 15: wandb_workspaces
• 15.1: Reports
• 15.2: Workspaces
• 16: watch

1 - agent

Start one or more sweep agents.

agent(
    sweep_id: str,
    function: Optional[Callable] = None,
    entity: Optional[str] = None,
    project: Optional[str] = None,
    count: Optional[int] = None
) -> None

The sweep agent uses the sweep_id to know which sweep it is a part of, what function to execute, and (optionally) how many agents to run.

2 - Artifact

Flexible and lightweight building block for dataset and model versioning.

Artifact(
    name: str,
    type: str,
    description: (str | None) = None,
    metadata: (dict[str, Any] | None) = None,
    incremental: bool = (False),
    use_as: (str | None) = None
) -> None

Construct an empty W&B Artifact. Populate an artifacts contents with methods that begin with add. Once the artifact has all the desired files, you can call wandb.log_artifact() to log it.

Methods

add

View source

add(
    obj: WBValue,
    name: StrPath,
    overwrite: bool = (False)
) -> ArtifactManifestEntry

Add wandb.WBValue obj to the artifact.

add_dir

View source

add_dir(
    local_path: str,
    name: (str | None) = None,
    skip_cache: (bool | None) = (False),
    policy: (Literal['mutable', 'immutable'] | None) = "mutable"
) -> None

Add a local directory to the artifact.

add_file

View source

add_file(
    local_path: str,
    name: (str | None) = None,
    is_tmp: (bool | None) = (False),
    skip_cache: (bool | None) = (False),
    policy: (Literal['mutable', 'immutable'] | None) = "mutable",
    overwrite: bool = (False)
) -> ArtifactManifestEntry

Add a local file to the artifact.

add_reference

View source

add_reference(
    uri: (ArtifactManifestEntry | str),
    name: (StrPath | None) = None,
    checksum: bool = (True),
    max_objects: (int | None) = None
) -> Sequence[ArtifactManifestEntry]

Add a reference denoted by a URI to the artifact.

Unlike files or directories that you add to an artifact, references are not uploaded to W&B. For more information, see Track external files.

By default, the following schemes are supported:

• http or https: The size and digest of the file will be inferred by the Content-Length and the ETag response headers returned by the server.
• s3: The checksum and size are pulled from the object metadata. If bucket versioning is enabled, then the version ID is also tracked.
• gs: The checksum and size are pulled from the object metadata. If bucket versioning is enabled, then the version ID is also tracked.
• https, domain matching *.blob.core.windows.net (Azure): The checksum and size are be pulled from the blob metadata. If storage account versioning is enabled, then the version ID is also tracked.
• file: The checksum and size are pulled from the file system. This scheme is useful if you have an NFS share or other externally mounted volume containing files you wish to track but not necessarily upload

For any other scheme, the digest is just a hash of the URI and the size is left blank.

checkout

View source

checkout(
    root: (str | None) = None
) -> str

Replace the specified root directory with the contents of the artifact.

delete

View source

delete(
    delete_aliases: bool = (False)
) -> None

Delete an artifact and its files.

If called on a linked artifact, such as a member of a portfolio collection, deletes only the link, not the source artifact.

download

View source

download(
    root: (StrPath | None) = None,
    allow_missing_references: bool = (False),
    skip_cache: (bool | None) = None,
    path_prefix: (StrPath | None) = None
) -> FilePathStr

Download the contents of the artifact to the specified root directory.

Existing files located within root are not modified. Explicitly delete root before you call download if you want the contents of root to exactly match the artifact.

file

View source

file(
    root: (str | None) = None
) -> StrPath

Download a single file artifact to the directory you specify with root.

files

View source

files(
    names: (list[str] | None) = None,
    per_page: int = 50
) -> ArtifactFiles

Iterate over all files stored in this artifact.

finalize

View source

finalize() -> None

Finalize the artifact version.

You cannot modify an artifact version once it is finalized because the artifact is logged as a specific artifact version. Create a new artifact version to log more data to an artifact. An artifact is automatically finalized when you log the artifact with log_artifact.

get

View source

get(
    name: str
) -> (WBValue | None)

Get the WBValue object located at the artifact relative name.

get_added_local_path_name

View source

get_added_local_path_name(
    local_path: str
) -> (str | None)

Get the artifact relative name of a file added by a local filesystem path.

get_entry

View source

get_entry(
    name: StrPath
) -> ArtifactManifestEntry

Get the entry with the given name.

get_path

View source

get_path(
    name: StrPath
) -> ArtifactManifestEntry

Deprecated. Use get_entry(name).

is_draft

View source

is_draft() -> bool

Check if artifact is not saved.

Returns: Boolean. False if artifact is saved. True if artifact is not saved.

json_encode

View source

json_encode() -> dict[str, Any]

Returns the artifact encoded to the JSON format.

link

View source

link(
    target_path: str,
    aliases: (list[str] | None) = None
) -> None

Link this artifact to a portfolio (a promoted collection of artifacts).

logged_by

View source

logged_by() -> (Run | None)

Get the W&B run that originally logged the artifact.

new_draft

View source

new_draft() -> Artifact

Create a new draft artifact with the same content as this committed artifact.

The artifact returned can be extended or modified and logged as a new version.

new_file

View source

@contextlib.contextmanager
new_file(
    name: str,
    mode: str = "x",
    encoding: (str | None) = None
) -> Iterator[IO]

Open a new temporary file and add it to the artifact.

remove

View source

remove(
    item: (StrPath | ArtifactManifestEntry)
) -> None

Remove an item from the artifact.

save

View source

save(
    project: (str | None) = None,
    settings: (wandb.Settings | None) = None
) -> None

Persist any changes made to the artifact.

If currently in a run, that run will log this artifact. If not currently in a run, a run of type “auto” is created to track this artifact.

unlink

View source

unlink() -> None

Unlink this artifact if it is currently a member of a portfolio (a promoted collection of artifacts).

used_by

View source

used_by() -> list[Run]

Get a list of the runs that have used this artifact.

verify

View source

verify(
    root: (str | None) = None
) -> None

Verify that the contents of an artifact match the manifest.

All files in the directory are checksummed and the checksums are then cross-referenced against the artifact’s manifest. References are not verified.

wait

View source

wait(
    timeout: (int | None) = None
) -> Artifact

If needed, wait for this artifact to finish logging.

__getitem__

View source

__getitem__(
    name: str
) -> (WBValue | None)

Get the WBValue object located at the artifact relative name.

__setitem__

View source

__setitem__(
    name: str,
    item: WBValue
) -> ArtifactManifestEntry

Add item to the artifact at path name.

3 - controller

Public sweep controller constructor.

controller(
    sweep_id_or_config: Optional[Union[str, Dict]] = None,
    entity: Optional[str] = None,
    project: Optional[str] = None
) -> "_WandbController"

Usage:

import wandb

tuner = wandb.controller(...)
print(tuner.sweep_config)
print(tuner.sweep_id)
tuner.configure_search(...)
tuner.configure_stopping(...)

4 - Data Types

This module defines data types for logging rich, interactive visualizations to W&B.

Data types include common media types, like images, audio, and videos, flexible containers for information, like tables and HTML, and more.

For more on logging media, see our guide

For more on logging structured data for interactive dataset and model analysis, see our guide to W&B Tables.

All of these special data types are subclasses of WBValue. All the data types serialize to JSON, since that is what wandb uses to save the objects locally and upload them to the W&B server.

Classes

class Audio: Wandb class for audio clips.

class BoundingBoxes2D: Format images with 2D bounding box overlays for logging to W&B.

class Graph: Wandb class for graphs.

class Histogram: wandb class for histograms.

class Html: Wandb class for arbitrary html.

class Image: Format images for logging to W&B.

class ImageMask: Format image masks or overlays for logging to W&B.

class Molecule: Wandb class for 3D Molecular data.

class Object3D: Wandb class for 3D point clouds.

class Plotly: Wandb class for plotly plots.

class Table: The Table class used to display and analyze tabular data.

class Video: Format a video for logging to W&B.

class WBTraceTree: Media object for trace tree data.

4.1 - Audio

Wandb class for audio clips.

Audio(
    data_or_path, sample_rate=None, caption=None
)

Methods

durations

View source

@classmethod
durations(
    audio_list
)

resolve_ref

View source

resolve_ref()

sample_rates

View source

@classmethod
sample_rates(
    audio_list
)

4.2 - BoundingBoxes2D

Format images with 2D bounding box overlays for logging to W&B.

BoundingBoxes2D(
    val: dict,
    key: str
) -> None

Examples:

Log bounding boxes for a single image

import numpy as np
import wandb

wandb.init()
image = np.random.randint(low=0, high=256, size=(200, 300, 3))

class_labels = {0: "person", 1: "car", 2: "road", 3: "building"}

img = wandb.Image(
    image,
    boxes={
        "predictions": {
            "box_data": [
                {
                    # one box expressed in the default relative/fractional domain
                    "position": {
                        "minX": 0.1,
                        "maxX": 0.2,
                        "minY": 0.3,
                        "maxY": 0.4,
                    },
                    "class_id": 1,
                    "box_caption": class_labels[1],
                    "scores": {"acc": 0.2, "loss": 1.2},
                },
                {
                    # another box expressed in the pixel domain
                    "position": {"middle": [150, 20], "width": 68, "height": 112},
                    "domain": "pixel",
                    "class_id": 3,
                    "box_caption": "a building",
                    "scores": {"acc": 0.5, "loss": 0.7},
                },
                # Log as many boxes an as needed
            ],
            "class_labels": class_labels,
        }
    },
)

wandb.log({"driving_scene": img})

Log a bounding box overlay to a Table

import numpy as np
import wandb

wandb.init()
image = np.random.randint(low=0, high=256, size=(200, 300, 3))

class_labels = {0: "person", 1: "car", 2: "road", 3: "building"}

class_set = wandb.Classes(
    [
        {"name": "person", "id": 0},
        {"name": "car", "id": 1},
        {"name": "road", "id": 2},
        {"name": "building", "id": 3},
    ]
)

img = wandb.Image(
    image,
    boxes={
        "predictions": {
            "box_data": [
                {
                    # one box expressed in the default relative/fractional domain
                    "position": {
                        "minX": 0.1,
                        "maxX": 0.2,
                        "minY": 0.3,
                        "maxY": 0.4,
                    },
                    "class_id": 1,
                    "box_caption": class_labels[1],
                    "scores": {"acc": 0.2, "loss": 1.2},
                },
                {
                    # another box expressed in the pixel domain
                    "position": {"middle": [150, 20], "width": 68, "height": 112},
                    "domain": "pixel",
                    "class_id": 3,
                    "box_caption": "a building",
                    "scores": {"acc": 0.5, "loss": 0.7},
                },
                # Log as many boxes an as needed
            ],
            "class_labels": class_labels,
        }
    },
    classes=class_set,
)

table = wandb.Table(columns=["image"])
table.add_data(img)
wandb.log({"driving_scene": table})

Methods

type_name

View source

@classmethod
type_name() -> str

validate

View source

validate(
    val: dict
) -> bool

4.3 - Graph

Wandb class for graphs.

Graph(
    format="keras"
)

This class is typically used for saving and displaying neural net models. It represents the graph as an array of nodes and edges. The nodes can have labels that can be visualized by wandb.

Examples:

Import a keras model:

Graph.from_keras(keras_model)

Methods

add_edge

View source

add_edge(
    from_node, to_node
)

add_node

View source

add_node(
    node=None, **node_kwargs
)

from_keras

View source

@classmethod
from_keras(
    model
)

pprint

View source

pprint()

__getitem__

View source

__getitem__(
    nid
)

4.4 - Histogram

wandb class for histograms.

Histogram(
    sequence: Optional[Sequence] = None,
    np_histogram: Optional['NumpyHistogram'] = None,
    num_bins: int = 64
) -> None

This object works just like numpy’s histogram function https://docs.scipy.org/doc/numpy/reference/generated/numpy.histogram.html

Examples:

Generate histogram from a sequence

wandb.Histogram([1, 2, 3])

Efficiently initialize from np.histogram.

hist = np.histogram(data)
wandb.Histogram(np_histogram=hist)

4.5 - Html

Wandb class for arbitrary html.

Html(
    data: Union[str, 'TextIO'],
    inject: bool = (True)
) -> None

Methods

inject_head

View source

inject_head() -> None

4.6 - Image

Format images for logging to W&B.

Image(
    data_or_path: "ImageDataOrPathType",
    mode: Optional[str] = None,
    caption: Optional[str] = None,
    grouping: Optional[int] = None,
    classes: Optional[Union['Classes', Sequence[dict]]] = None,
    boxes: Optional[Union[Dict[str, 'BoundingBoxes2D'], Dict[str, dict]]] = None,
    masks: Optional[Union[Dict[str, 'ImageMask'], Dict[str, dict]]] = None,
    file_type: Optional[str] = None
) -> None

Note : When logging a torch.Tensor as a wandb.Image, images are normalized. If you do not want to normalize your images, please convert your tensors to a PIL Image.

Examples:

Create a wandb.Image from a numpy array

import numpy as np
import wandb

with wandb.init() as run:
    examples = []
    for i in range(3):
        pixels = np.random.randint(low=0, high=256, size=(100, 100, 3))
        image = wandb.Image(pixels, caption=f"random field {i}")
        examples.append(image)
    run.log({"examples": examples})

Create a wandb.Image from a PILImage

import numpy as np
from PIL import Image as PILImage
import wandb

with wandb.init() as run:
    examples = []
    for i in range(3):
        pixels = np.random.randint(
            low=0, high=256, size=(100, 100, 3), dtype=np.uint8
        )
        pil_image = PILImage.fromarray(pixels, mode="RGB")
        image = wandb.Image(pil_image, caption=f"random field {i}")
        examples.append(image)
    run.log({"examples": examples})

log .jpg rather than .png (default)

import numpy as np
import wandb

with wandb.init() as run:
    examples = []
    for i in range(3):
        pixels = np.random.randint(low=0, high=256, size=(100, 100, 3))
        image = wandb.Image(pixels, caption=f"random field {i}", file_type="jpg")
        examples.append(image)
    run.log({"examples": examples})

Methods

all_boxes

View source

@classmethod
all_boxes(
    images: Sequence['Image'],
    run: "LocalRun",
    run_key: str,
    step: Union[int, str]
) -> Union[List[Optional[dict]], bool]

all_captions

View source

@classmethod
all_captions(
    images: Sequence['Media']
) -> Union[bool, Sequence[Optional[str]]]

all_masks

View source

@classmethod
all_masks(
    images: Sequence['Image'],
    run: "LocalRun",
    run_key: str,
    step: Union[int, str]
) -> Union[List[Optional[dict]], bool]

guess_mode

View source

guess_mode(
    data: "np.ndarray"
) -> str

Guess what type of image the np.array is representing.

to_uint8

View source

@classmethod
to_uint8(
    data: "np.ndarray"
) -> "np.ndarray"

Convert image data to uint8.

Convert floating point image on the range [0,1] and integer images on the range [0,255] to uint8, clipping if necessary.

4.7 - ImageMask

Format image masks or overlays for logging to W&B.

ImageMask(
    val: dict,
    key: str
) -> None

Examples:

Logging a single masked image

import numpy as np
import wandb

wandb.init()
image = np.random.randint(low=0, high=256, size=(100, 100, 3), dtype=np.uint8)
predicted_mask = np.empty((100, 100), dtype=np.uint8)
ground_truth_mask = np.empty((100, 100), dtype=np.uint8)

predicted_mask[:50, :50] = 0
predicted_mask[50:, :50] = 1
predicted_mask[:50, 50:] = 2
predicted_mask[50:, 50:] = 3

ground_truth_mask[:25, :25] = 0
ground_truth_mask[25:, :25] = 1
ground_truth_mask[:25, 25:] = 2
ground_truth_mask[25:, 25:] = 3

class_labels = {0: "person", 1: "tree", 2: "car", 3: "road"}

masked_image = wandb.Image(
    image,
    masks={
        "predictions": {"mask_data": predicted_mask, "class_labels": class_labels},
        "ground_truth": {
            "mask_data": ground_truth_mask,
            "class_labels": class_labels,
        },
    },
)
wandb.log({"img_with_masks": masked_image})

Log a masked image inside a Table

import numpy as np
import wandb

wandb.init()
image = np.random.randint(low=0, high=256, size=(100, 100, 3), dtype=np.uint8)
predicted_mask = np.empty((100, 100), dtype=np.uint8)
ground_truth_mask = np.empty((100, 100), dtype=np.uint8)

predicted_mask[:50, :50] = 0
predicted_mask[50:, :50] = 1
predicted_mask[:50, 50:] = 2
predicted_mask[50:, 50:] = 3

ground_truth_mask[:25, :25] = 0
ground_truth_mask[25:, :25] = 1
ground_truth_mask[:25, 25:] = 2
ground_truth_mask[25:, 25:] = 3

class_labels = {0: "person", 1: "tree", 2: "car", 3: "road"}

class_set = wandb.Classes(
    [
        {"name": "person", "id": 0},
        {"name": "tree", "id": 1},
        {"name": "car", "id": 2},
        {"name": "road", "id": 3},
    ]
)

masked_image = wandb.Image(
    image,
    masks={
        "predictions": {"mask_data": predicted_mask, "class_labels": class_labels},
        "ground_truth": {
            "mask_data": ground_truth_mask,
            "class_labels": class_labels,
        },
    },
    classes=class_set,
)

table = wandb.Table(columns=["image"])
table.add_data(masked_image)
wandb.log({"random_field": table})

Methods

type_name

View source

@classmethod
type_name() -> str

validate

View source

validate(
    val: dict
) -> bool

4.8 - Molecule

Wandb class for 3D Molecular data.

Molecule(
    data_or_path: Union[str, 'TextIO'],
    caption: Optional[str] = None,
    **kwargs
) -> None

Methods

from_rdkit

View source

@classmethod
from_rdkit(
    data_or_path: "RDKitDataType",
    caption: Optional[str] = None,
    convert_to_3d_and_optimize: bool = (True),
    mmff_optimize_molecule_max_iterations: int = 200
) -> "Molecule"

Convert RDKit-supported file/object types to wandb.Molecule.

from_smiles

View source

@classmethod
from_smiles(
    data: str,
    caption: Optional[str] = None,
    sanitize: bool = (True),
    convert_to_3d_and_optimize: bool = (True),
    mmff_optimize_molecule_max_iterations: int = 200
) -> "Molecule"

Convert SMILES string to wandb.Molecule.

4.9 - Object3D

Wandb class for 3D point clouds.

Object3D(
    data_or_path: Union['np.ndarray', str, 'TextIO', dict],
    **kwargs
) -> None

The shape of the numpy array must be one of either:

[[x y z],       ...] nx3
[[x y z c],     ...] nx4 where c is a category with supported range [1, 14]
[[x y z r g b], ...] nx6 where is rgb is color

Methods

from_file

View source

@classmethod
from_file(
    data_or_path: Union['TextIO', str],
    file_type: Optional['FileFormat3D'] = None
) -> "Object3D"

Initializes Object3D from a file or stream.

from_numpy

View source

@classmethod
from_numpy(
    data: "np.ndarray"
) -> "Object3D"

Initializes Object3D from a numpy array.

The shape of the numpy array must be one of either:

[[x y z],       ...]  # nx3.
[[x y z c],     ...]  # nx4 where c is a category with supported range [1, 14].
[[x y z r g b], ...]  # nx6 where is rgb is color.

from_point_cloud

View source

@classmethod
from_point_cloud(
    points: Sequence['Point'],
    boxes: Sequence['Box3D'],
    vectors: Optional[Sequence['Vector3D']] = None,
    point_cloud_type: "PointCloudType" = "lidar/beta"
) -> "Object3D"

Initializes Object3D from a python object.

4.10 - Plotly

Wandb class for plotly plots.

Plotly(
    val: Union['plotly.Figure', 'matplotlib.artist.Artist']
)

Methods

make_plot_media

View source

@classmethod
make_plot_media(
    val: Union['plotly.Figure', 'matplotlib.artist.Artist']
) -> Union[Image, 'Plotly']

4.11 - Table

The Table class used to display and analyze tabular data.

Table(
  columns=None, data=None, rows=None, dataframe=None, dtype=None, optional=(True),
  allow_mixed_types=(False)
)

Unlike traditional spreadsheets, Tables support numerous types of data: scalar values, strings, numpy arrays, and most subclasses of wandb.data_types.Media. This means you can embed Images, Video, Audio, and other sorts of rich, annotated media directly in Tables, alongside other traditional scalar values.

This class is the primary class used to generate the Table Visualizer in the UI: https://docs.wandb.ai/guides/data-vis/tables.

Methods

add_column

View source

add_column(
  name, data, optional=(False)
)

Adds a column of data to the table.

add_computed_columns

View source

add_computed_columns(
  fn
)

Adds one or more computed columns based on existing data.

add_data

View source

add_data(
  *data
)

Adds a new row of data to the table. The maximum amount of rows in a table is determined by wandb.Table.MAX_ARTIFACT_ROWS.

The length of the data should match the length of the table column.

add_row

View source

add_row(
  *row
)

Deprecated. Use add_data instead.

cast

View source

cast(
  col_name, dtype, optional=(False)
)

Casts a column to a specific data type.

This can be one of the normal python classes, an internal W&B type, or an example object, like an instance of wandb.Image or wandb.Classes.

get_column

View source

get_column(
  name, convert_to=None
)

Retrieves a column from the table and optionally converts it to a NumPy object.

get_dataframe

View source

get_dataframe()

Returns a pandas.DataFrame of the table.

get_index

View source

get_index()

Returns an array of row indexes for use in other tables to create links.

index_ref

View source

index_ref(
  index
)

Gets a reference of the index of a row in the table.

iterrows

View source

iterrows()

Returns the table data by row, showing the index of the row and the relevant data.

index : int The index of the row. Using this value in other W&B tables will automatically build a relationship between the tables row : List[any] The data of the row.

set_fk

View source

set_fk(
  col_name, table, table_col
)

set_pk

View source

set_pk(
  col_name
)

4.12 - Video

Format a video for logging to W&B.

Video(
    data_or_path: Union['np.ndarray', str, 'TextIO', 'BytesIO'],
    caption: Optional[str] = None,
    fps: Optional[int] = None,
    format: Optional[str] = None
)

Examples:

Log a numpy array as a video

import numpy as np
import wandb

wandb.init()
# axes are (time, channel, height, width)
frames = np.random.randint(low=0, high=256, size=(10, 3, 100, 100), dtype=np.uint8)
wandb.log({"video": wandb.Video(frames, fps=4)})

Methods

encode

View source

encode(
    fps: int = 4
) -> None

4.13 - WBTraceTree

Media object for trace tree data.

WBTraceTree(
    root_span: Span,
    model_dict: typing.Optional[dict] = None
)

5 - finish

Finish a run and upload any remaining data.

finish(
    exit_code: (int | None) = None,
    quiet: (bool | None) = None
) -> None

Marks the completion of a W&B run and ensures all data is synced to the server. The run’s final state is determined by its exit conditions and sync status.

Run States:

• Running: Active run that is logging data and/or sending heartbeats.
• Crashed: Run that stopped sending heartbeats unexpectedly.
• Finished: Run completed successfully (exit_code=0) with all data synced.
• Failed: Run completed with errors (exit_code!=0).

6 - Import & Export API

Classes

class Api: Used for querying the wandb server.

class File: File is a class associated with a file saved by wandb.

class Files: An iterable collection of File objects.

class Job

class Project: A project is a namespace for runs.

class Projects: An iterable collection of Project objects.

class QueuedRun: A single queued run associated with an entity and project. Call run = queued_run.wait_until_running() or run = queued_run.wait_until_finished() to access the run.

class Run: A single run associated with an entity and project.

class RunQueue

class Runs: An iterable collection of runs associated with a project and optional filter.

class Sweep: A set of runs associated with a sweep.

6.1 - Api

Used for querying the wandb server.

Api(
    overrides: Optional[Dict[str, Any]] = None,
    timeout: Optional[int] = None,
    api_key: Optional[str] = None
) -> None

Examples:

Most common way to initialize

>>> wandb.Api()

Methods

artifact

View source

artifact(
    name: str,
    type: Optional[str] = None
)

Return a single artifact by parsing path in the form project/name or entity/project/name.

Note:

This method is intended for external use only. Do not call api.artifact() within the wandb repository code.

artifact_collection

View source

artifact_collection(
    type_name: str,
    name: str
) -> "public.ArtifactCollection"

Return a single artifact collection by type and parsing path in the form entity/project/name.

artifact_collection_exists

View source

artifact_collection_exists(
    name: str,
    type: str
) -> bool

Return whether an artifact collection exists within a specified project and entity.

artifact_collections

View source

artifact_collections(
    project_name: str,
    type_name: str,
    per_page: Optional[int] = 50
) -> "public.ArtifactCollections"

Return a collection of matching artifact collections.

artifact_exists

View source

artifact_exists(
    name: str,
    type: Optional[str] = None
) -> bool

Return whether an artifact version exists within a specified project and entity.

artifact_type

View source

artifact_type(
    type_name: str,
    project: Optional[str] = None
) -> "public.ArtifactType"

Return the matching ArtifactType.

artifact_types

View source

artifact_types(
    project: Optional[str] = None
) -> "public.ArtifactTypes"

Return a collection of matching artifact types.

artifact_versions

View source

artifact_versions(
    type_name, name, per_page=50
)

Deprecated, use artifacts(type_name, name) instead.

artifacts

View source

artifacts(
    type_name: str,
    name: str,
    per_page: Optional[int] = 50,
    tags: Optional[List[str]] = None
) -> "public.Artifacts"

Return an Artifacts collection from the given parameters.

create_project

View source

create_project(
    name: str,
    entity: str
) -> None

Create a new project.

create_run

View source

create_run(
    *,
    run_id: Optional[str] = None,
    project: Optional[str] = None,
    entity: Optional[str] = None
) -> "public.Run"

Create a new run.

create_run_queue

View source

create_run_queue(
    name: str,
    type: "public.RunQueueResourceType",
    entity: Optional[str] = None,
    prioritization_mode: Optional['public.RunQueuePrioritizationMode'] = None,
    config: Optional[dict] = None,
    template_variables: Optional[dict] = None
) -> "public.RunQueue"

Create a new run queue (launch).

create_team

View source

create_team(
    team, admin_username=None
)

Create a new team.

create_user

View source

create_user(
    email, admin=(False)
)

Create a new user.

flush

View source

flush()

Flush the local cache.

The api object keeps a local cache of runs, so if the state of the run may change while executing your script you must clear the local cache with api.flush() to get the latest values associated with the run.

from_path

View source

from_path(
    path
)

Return a run, sweep, project, or report from a path.

Examples:

project = api.from_path("my_project")
team_project = api.from_path("my_team/my_project")
run = api.from_path("my_team/my_project/runs/id")
sweep = api.from_path("my_team/my_project/sweeps/id")
report = api.from_path("my_team/my_project/reports/My-Report-Vm11dsdf")

job

View source

job(
    name: Optional[str],
    path: Optional[str] = None
) -> "public.Job"

Return a Job from the given parameters.

list_jobs

View source

list_jobs(
    entity: str,
    project: str
) -> List[Dict[str, Any]]

Return a list of jobs, if any, for the given entity and project.

project

View source

project(
    name: str,
    entity: Optional[str] = None
) -> "public.Project"

Return the Project with the given name (and entity, if given).

projects

View source

projects(
    entity: Optional[str] = None,
    per_page: Optional[int] = 200
) -> "public.Projects"

Get projects for a given entity.

queued_run

View source

queued_run(
    entity, project, queue_name, run_queue_item_id, project_queue=None,
    priority=None
)

Return a single queued run based on the path.

Parses paths of the form entity/project/queue_id/run_queue_item_id.

reports

View source

reports(
    path: str = "",
    name: Optional[str] = None,
    per_page: Optional[int] = 50
) -> "public.Reports"

Get reports for a given project path.

WARNING: This api is in beta and will likely change in a future release

run

View source

run(
    path=""
)

Return a single run by parsing path in the form entity/project/run_id.

run_queue

View source

run_queue(
    entity, name
)

Return the named RunQueue for entity.

To create a new RunQueue, use wandb.Api().create_run_queue(...).

runs

View source

runs(
    path: Optional[str] = None,
    filters: Optional[Dict[str, Any]] = None,
    order: str = "+created_at",
    per_page: int = 50,
    include_sweeps: bool = (True)
)

Return a set of runs from a project that match the filters provided.

You can filter by config.*, summary_metrics.*, tags, state, entity, createdAt, etc.

Examples:

Find runs in my_project where config.experiment_name has been set to “foo”

api.runs(path="my_entity/my_project", filters={"config.experiment_name": "foo"})

Find runs in my_project where config.experiment_name has been set to “foo” or “bar”

api.runs(
    path="my_entity/my_project",
    filters={
        "$or": [
            {"config.experiment_name": "foo"},
            {"config.experiment_name": "bar"},
        ]
    },
)

Find runs in my_project where config.experiment_name matches a regex (anchors are not supported)

api.runs(
    path="my_entity/my_project",
    filters={"config.experiment_name": {"$regex": "b.*"}},
)

Find runs in my_project where the run name matches a regex (anchors are not supported)

api.runs(
    path="my_entity/my_project", filters={"display_name": {"$regex": "^foo.*"}}
)

Find runs in my_project sorted by ascending loss

api.runs(path="my_entity/my_project", order="+summary_metrics.loss")

sweep

View source

sweep(
    path=""
)

Return a sweep by parsing path in the form entity/project/sweep_id.

sync_tensorboard

View source

sync_tensorboard(
    root_dir, run_id=None, project=None, entity=None
)

Sync a local directory containing tfevent files to wandb.

team

View source

team(
    team: str
) -> "public.Team"

Return the matching Team with the given name.

upsert_run_queue

View source

upsert_run_queue(
    name: str,
    resource_config: dict,
    resource_type: "public.RunQueueResourceType",
    entity: Optional[str] = None,
    template_variables: Optional[dict] = None,
    external_links: Optional[dict] = None,
    prioritization_mode: Optional['public.RunQueuePrioritizationMode'] = None
)

Upsert a run queue (launch).

user

View source

user(
    username_or_email: str
) -> Optional['public.User']

Return a user from a username or email address.

Note: This function only works for Local Admins, if you are trying to get your own user object, please use api.viewer.

users

View source

users(
    username_or_email: str
) -> List['public.User']

Return all users from a partial username or email address query.

Note: This function only works for Local Admins, if you are trying to get your own user object, please use api.viewer.

6.2 - File

File is a class associated with a file saved by wandb.

File(
    client, attrs, run=None
)

Methods

delete

View source

delete()

display

View source

display(
    height=420, hidden=(False)
) -> bool

Display this object in jupyter.

download

View source

download(
    root: str = ".",
    replace: bool = (False),
    exist_ok: bool = (False),
    api: Optional[Api] = None
) -> io.TextIOWrapper

Downloads a file previously saved by a run from the wandb server.

snake_to_camel

View source

snake_to_camel(
    string
)

to_html

View source

to_html(
    *args, **kwargs
)

6.3 - Files

An iterable collection of File objects.

Files(
    client, run, names=None, per_page=50, upload=(False)
)

Methods

convert_objects

View source

convert_objects()

next

View source

next()

update_variables

View source

update_variables()

__getitem__

View source

__getitem__(
    index
)

__iter__

View source

__iter__()

__len__

View source

__len__()

6.4 - Job

Job(
    api: "Api",
    name,
    path: Optional[str] = None
) -> None

Methods

call

View source

call(
    config, project=None, entity=None, queue=None, resource="local-container",
    resource_args=None, template_variables=None, project_queue=None, priority=None
)

set_entrypoint

View source

set_entrypoint(
    entrypoint: List[str]
)

6.5 - Project

A project is a namespace for runs.

Project(
    client, entity, project, attrs
)

Methods

artifacts_types

View source

artifacts_types(
    per_page=50
)

display

View source

display(
    height=420, hidden=(False)
) -> bool

Display this object in jupyter.

snake_to_camel

View source

snake_to_camel(
    string
)

sweeps

View source

sweeps()

to_html

View source

to_html(
    height=420, hidden=(False)
)

Generate HTML containing an iframe displaying this project.

6.6 - Projects

An iterable collection of Project objects.

Projects(
    client, entity, per_page=50
)

Methods

convert_objects

View source

convert_objects()

next

View source

next()

update_variables

View source

update_variables()

__getitem__

View source

__getitem__(
    index
)

__iter__

View source

__iter__()

__len__

View source

__len__()

6.7 - QueuedRun

A single queued run associated with an entity and project. Call run = queued_run.wait_until_running() or run = queued_run.wait_until_finished() to access the run.

QueuedRun(
    client, entity, project, queue_name, run_queue_item_id,
    project_queue=LAUNCH_DEFAULT_PROJECT, priority=None
)

Methods

delete

View source

delete(
    delete_artifacts=(False)
)

Delete the given queued run from the wandb backend.

wait_until_finished

View source

wait_until_finished()

wait_until_running

View source

wait_until_running()

6.8 - Run

A single run associated with an entity and project.

Run(
    client: "RetryingClient",
    entity: str,
    project: str,
    run_id: str,
    attrs: Optional[Mapping] = None,
    include_sweeps: bool = (True)
)

Methods

create

View source

@classmethod
create(
    api, run_id=None, project=None, entity=None
)

Create a run for the given project.

delete

View source

delete(
    delete_artifacts=(False)
)

Delete the given run from the wandb backend.

display

View source

display(
    height=420, hidden=(False)
) -> bool

Display this object in jupyter.

file

View source

file(
    name
)

Return the path of a file with a given name in the artifact.

files

View source

files(
    names=None, per_page=50
)

Return a file path for each file named.

history

View source

history(
    samples=500, keys=None, x_axis="_step", pandas=(True), stream="default"
)

Return sampled history metrics for a run.

This is simpler and faster if you are ok with the history records being sampled.

load

View source

load(
    force=(False)
)

log_artifact

View source

log_artifact(
    artifact: "wandb.Artifact",
    aliases: Optional[Collection[str]] = None,
    tags: Optional[Collection[str]] = None
)

Declare an artifact as output of a run.

logged_artifacts

View source

logged_artifacts(
    per_page: int = 100
) -> public.RunArtifacts

Fetches all artifacts logged by this run.

Retrieves all output artifacts that were logged during the run. Returns a paginated result that can be iterated over or collected into a single list.

Example:

>>> import wandb
>>> import tempfile
>>> with tempfile.NamedTemporaryFile(
...     mode="w", delete=False, suffix=".txt"
... ) as tmp:
...     tmp.write("This is a test artifact")
...     tmp_path = tmp.name
>>> run = wandb.init(project="artifact-example")
>>> artifact = wandb.Artifact("test_artifact", type="dataset")
>>> artifact.add_file(tmp_path)
>>> run.log_artifact(artifact)
>>> run.finish()
>>> api = wandb.Api()
>>> finished_run = api.run(f"{run.entity}/{run.project}/{run.id}")
>>> for logged_artifact in finished_run.logged_artifacts():
...     print(logged_artifact.name)
test_artifact

save

View source

save()

scan_history

View source

scan_history(
    keys=None, page_size=1000, min_step=None, max_step=None
)

Returns an iterable collection of all history records for a run.

Example:

Export all the loss values for an example run

run = api.run("l2k2/examples-numpy-boston/i0wt6xua")
history = run.scan_history(keys=["Loss"])
losses = [row["Loss"] for row in history]

snake_to_camel

View source

snake_to_camel(
    string
)

to_html

View source

to_html(
    height=420, hidden=(False)
)

Generate HTML containing an iframe displaying this run.

update

View source

update()

Persist changes to the run object to the wandb backend.

upload_file

View source

upload_file(
    path, root="."
)

Upload a file.

use_artifact

View source

use_artifact(
    artifact, use_as=None
)

Declare an artifact as an input to a run.

used_artifacts

View source

used_artifacts(
    per_page: int = 100
) -> public.RunArtifacts

Fetches artifacts explicitly used by this run.

Retrieves only the input artifacts that were explicitly declared as used during the run, typically via run.use_artifact(). Returns a paginated result that can be iterated over or collected into a single list.

Example:

>>> import wandb
>>> run = wandb.init(project="artifact-example")
>>> run.use_artifact("test_artifact:latest")
>>> run.finish()
>>> api = wandb.Api()
>>> finished_run = api.run(f"{run.entity}/{run.project}/{run.id}")
>>> for used_artifact in finished_run.used_artifacts():
...     print(used_artifact.name)
test_artifact

wait_until_finished

View source

wait_until_finished()

6.9 - RunQueue

RunQueue(
    client: "RetryingClient",
    name: str,
    entity: str,
    prioritization_mode: Optional[RunQueuePrioritizationMode] = None,
    _access: Optional[RunQueueAccessType] = None,
    _default_resource_config_id: Optional[int] = None,
    _default_resource_config: Optional[dict] = None
) -> None

Methods

create

View source

@classmethod
create(
    name: str,
    resource: "RunQueueResourceType",
    entity: Optional[str] = None,
    prioritization_mode: Optional['RunQueuePrioritizationMode'] = None,
    config: Optional[dict] = None,
    template_variables: Optional[dict] = None
) -> "RunQueue"

delete

View source

delete()

Delete the run queue from the wandb backend.

6.10 - Runs

An iterable collection of runs associated with a project and optional filter.

Runs(
    client: "RetryingClient",
    entity: str,
    project: str,
    filters: Optional[Dict[str, Any]] = None,
    order: Optional[str] = None,
    per_page: int = 50,
    include_sweeps: bool = (True)
)

This is generally used indirectly via the Api.runs method.

Methods

convert_objects

View source

convert_objects()

histories

View source

histories(
    samples: int = 500,
    keys: Optional[List[str]] = None,
    x_axis: str = "_step",
    format: Literal['default', 'pandas', 'polars'] = "default",
    stream: Literal['default', 'system'] = "default"
)

Return sampled history metrics for all runs that fit the filters conditions.

next

View source

next()

update_variables

View source

update_variables()

__getitem__

View source

__getitem__(
    index
)

__iter__

View source

__iter__()

__len__

View source

__len__()

6.11 - Sweep

A set of runs associated with a sweep.

Sweep(
    client, entity, project, sweep_id, attrs=None
)

Examples:

Instantiate with:

api = wandb.Api()
sweep = api.sweep(path / to / sweep)

Methods

best_run

View source

best_run(
    order=None
)

Return the best run sorted by the metric defined in config or the order passed in.

display

View source

display(
    height=420, hidden=(False)
) -> bool

Display this object in jupyter.

get

View source

@classmethod
get(
    client, entity=None, project=None, sid=None, order=None, query=None, **kwargs
)

Execute a query against the cloud backend.

load

View source

load(
    force: bool = (False)
)

snake_to_camel

View source

snake_to_camel(
    string
)

to_html

View source

to_html(
    height=420, hidden=(False)
)

Generate HTML containing an iframe displaying this sweep.

7 - init

Start a new run to track and log to W&B.

init(
    entity: (str | None) = None,
    project: (str | None) = None,
    dir: (StrPath | None) = None,
    id: (str | None) = None,
    name: (str | None) = None,
    notes: (str | None) = None,
    tags: (Sequence[str] | None) = None,
    config: (dict[str, Any] | str | None) = None,
    config_exclude_keys: (list[str] | None) = None,
    config_include_keys: (list[str] | None) = None,
    allow_val_change: (bool | None) = None,
    group: (str | None) = None,
    job_type: (str | None) = None,
    mode: (Literal['online', 'offline', 'disabled'] | None) = None,
    force: (bool | None) = None,
    anonymous: (Literal['never', 'allow', 'must'] | None) = None,
    reinit: (bool | None) = None,
    resume: (bool | Literal['allow', 'never', 'must', 'auto'] | None) = None,
    resume_from: (str | None) = None,
    fork_from: (str | None) = None,
    save_code: (bool | None) = None,
    tensorboard: (bool | None) = None,
    sync_tensorboard: (bool | None) = None,
    monitor_gym: (bool | None) = None,
    settings: (Settings | dict[str, Any] | None) = None
) -> Run

In an ML training pipeline, you could add wandb.init() to the beginning of your training script as well as your evaluation script, and each piece would be tracked as a run in W&B.

wandb.init() spawns a new background process to log data to a run, and it also syncs data to https://wandb.ai by default, so you can see your results in real-time.

Call wandb.init() to start a run before logging data with wandb.log(). When you’re done logging data, call wandb.finish() to end the run. If you don’t call wandb.finish(), the run ends when your script exits.

For more on using wandb.init(), including detailed examples, check out our guide and FAQs.

Examples: