Functions

• 1: agent()
• 2: controller()
• 3: finish()
• 4: init()
• 5: login()
• 6: restore()
• 7: setup()
• 8: sweep()
• 9: teardown()

1 - agent()

function agent

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

Start one or more sweep agents.

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.

Args:

• sweep_id: The unique identifier for a sweep. A sweep ID is generated by W&B CLI or Python SDK.
• function: A function to call instead of the “program” specified in the sweep config.
• entity: The username or team name where you want to send W&B runs created by the sweep to. Ensure that the entity you specify already exists. If you don’t specify an entity, the run will be sent to your default entity, which is usually your username.
• project: The name of the project where W&B runs created from the sweep are sent to. If the project is not specified, the run is sent to a project labeled “Uncategorized”.
• count: The number of sweep config trials to try.

2 - controller()

function controller

controller(
    sweep_id_or_config: Optional[str, Dict] = None,
    entity: Optional[str] = None,
    project: Optional[str] = None
) → _WandbController

Public sweep controller constructor.

Examples:

import wandb

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

3 - finish()

function finish

finish(exit_code: 'int | None' = None, quiet: 'bool | None' = None) → None

Finish a run and upload any remaining data.

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

Args:

• exit_code: Integer indicating the run’s exit status. Use 0 for success, any other value marks the run as failed.
• quiet: Deprecated. Configure logging verbosity using wandb.Settings(quiet=...).

4 - init()

function init

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 | Literal[None, 'default', 'return_previous', 'finish_previous', 'create_new']" = 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

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

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. When you’re done logging data, call wandb.finish() to end the run. If you don’t call run.finish(), the run will end when your script exits.

Run IDs must not contain any of the following special characters / \ # ? % :

Args:

• entity: The username or team name the runs are logged to. The entity must already exist, so ensure you create your account or team in the UI before starting to log runs. If not specified, the run will default your default entity. To change the default entity, go to your settings and update the “Default location to create new projects” under “Default team”.
• project: The name of the project under which this run will be logged. If not specified, we use a heuristic to infer the project name based on the system, such as checking the git root or the current program file. If we can’t infer the project name, the project will default to "uncategorized".
• dir: The absolute path to the directory where experiment logs and metadata files are stored. If not specified, this defaults to the ./wandb directory. Note that this does not affect the location where artifacts are stored when calling download().
• id: A unique identifier for this run, used for resuming. It must be unique within the project and cannot be reused once a run is deleted. For a short descriptive name, use the name field, or for saving hyperparameters to compare across runs, use config.
• name: A short display name for this run, which appears in the UI to help you identify it. By default, we generate a random two-word name allowing easy cross-reference runs from table to charts. Keeping these run names brief enhances readability in chart legends and tables. For saving hyperparameters, we recommend using the config field.
• notes: A detailed description of the run, similar to a commit message in Git. Use this argument to capture any context or details that may help you recall the purpose or setup of this run in the future.
• tags: A list of tags to label this run in the UI. Tags are helpful for organizing runs or adding temporary identifiers like “baseline” or “production.” You can easily add, remove tags, or filter by tags in the UI. If resuming a run, the tags provided here will replace any existing tags. To add tags to a resumed run without overwriting the current tags, use run.tags += ["new_tag"] after calling run = wandb.init().
• config: Sets wandb.config, a dictionary-like object for storing input parameters to your run, such as model hyperparameters or data preprocessing settings. The config appears in the UI in an overview page, allowing you to group, filter, and sort runs based on these parameters. Keys should not contain periods (.), and values should be smaller than 10 MB. If a dictionary, argparse.Namespace, or absl.flags.FLAGS is provided, the key-value pairs will be loaded directly into wandb.config. If a string is provided, it is interpreted as a path to a YAML file, from which configuration values will be loaded into wandb.config.
• config_exclude_keys: A list of specific keys to exclude from wandb.config.
• config_include_keys: A list of specific keys to include in wandb.config.
• allow_val_change: Controls whether config values can be modified after their initial set. By default, an exception is raised if a config value is overwritten. For tracking variables that change during training, such as a learning rate, consider using wandb.log() instead. By default, this is False in scripts and True in Notebook environments.
• group: Specify a group name to organize individual runs as part of a larger experiment. This is useful for cases like cross-validation or running multiple jobs that train and evaluate a model on different test sets. Grouping allows you to manage related runs collectively in the UI, making it easy to toggle and review results as a unified experiment.
• job_type: Specify the type of run, especially helpful when organizing runs within a group as part of a larger experiment. For example, in a group, you might label runs with job types such as “train” and “eval”. Defining job types enables you to easily filter and group similar runs in the UI, facilitating direct comparisons.
• mode: Specifies how run data is managed, with the following options:
  • "online" (default): Enables live syncing with W&B when a network connection is available, with real-time updates to visualizations.
  • "offline": Suitable for air-gapped or offline environments; data is saved locally and can be synced later. Ensure the run folder is preserved to enable future syncing.
  • "disabled": Disables all W&B functionality, making the run’s methods no-ops. Typically used in testing to bypass W&B operations.
• force: Determines if a W&B login is required to run the script. If True, the user must be logged in to W&B; otherwise, the script will not proceed. If False (default), the script can proceed without a login, switching to offline mode if the user is not logged in.
• anonymous: Specifies the level of control over anonymous data logging. Available options are:
  • "never" (default): Requires you to link your W&B account before tracking the run. This prevents unintentional creation of anonymous runs by ensuring each run is associated with an account.
  • "allow": Enables a logged-in user to track runs with their account, but also allows someone running the script without a W&B account to view the charts and data in the UI.
  • "must": Forces the run to be logged to an anonymous account, even if the user is logged in.
• reinit: Shorthand for the “reinit” setting. Determines the behavior of wandb.init() when a run is active.
• resume: Controls the behavior when resuming a run with the specified id. Available options are:
  • "allow": If a run with the specified id exists, it will resume from the last step; otherwise, a new run will be created.
  • "never": If a run with the specified id exists, an error will be raised. If no such run is found, a new run will be created.
  • "must": If a run with the specified id exists, it will resume from the last step. If no run is found, an error will be raised.
  • "auto": Automatically resumes the previous run if it crashed on this machine; otherwise, starts a new run.
  • True: Deprecated. Use "auto" instead.
  • False: Deprecated. Use the default behavior (leaving resume unset) to always start a new run. If resume is set, fork_from and resume_from cannot be used. When resume is unset, the system will always start a new run.
• resume_from: Specifies a moment in a previous run to resume a run from, using the format {run_id}?_step={step}. This allows users to truncate the history logged to a run at an intermediate step and resume logging from that step. The target run must be in the same project. If an id argument is also provided, the resume_from argument will take precedence. resume, resume_from and fork_from cannot be used together, only one of them can be used at a time. Note that this feature is in beta and may change in the future.
• fork_from: Specifies a point in a previous run from which to fork a new run, using the format {id}?_step={step}. This creates a new run that resumes logging from the specified step in the target run’s history. The target run must be part of the current project. If an id argument is also provided, it must be different from the fork_from argument, an error will be raised if they are the same. resume, resume_from and fork_from cannot be used together, only one of them can be used at a time. Note that this feature is in beta and may change in the future.
• save_code: Enables saving the main script or notebook to W&B, aiding in experiment reproducibility and allowing code comparisons across runs in the UI. By default, this is disabled, but you can change the default to enable on your settings page.
• tensorboard: Deprecated. Use sync_tensorboard instead.
• sync_tensorboard: Enables automatic syncing of W&B logs from TensorBoard or TensorBoardX, saving relevant event files for viewing in the W&B UI.
• saving relevant event files for viewing in the W&B UI. (Default: False)
• monitor_gym: Enables automatic logging of videos of the environment when using OpenAI Gym.
• settings: Specifies a dictionary or wandb.Settings object with advanced settings for the run.

Raises:

• Error: if some unknown or internal error happened during the run initialization.
• AuthenticationError: if the user failed to provide valid credentials.
• CommError: if there was a problem communicating with the WandB server.
• UsageError: if the user provided invalid arguments.
• KeyboardInterrupt: if user interrupts the run.

Returns: A Run object.

Examples: wandb.init() returns a run object, and you can also access the run object with wandb.run:

import wandb

config = {"lr": 0.01, "batch_size": 32}
with wandb.init(config=config) as run:
    run.config.update({"architecture": "resnet", "depth": 34})

    # ... your training code here ...

5 - login()

function login

login(
    anonymous: Optional[Literal['must', 'allow', 'never']] = None,
    key: Optional[str] = None,
    relogin: Optional[bool] = None,
    host: Optional[str] = None,
    force: Optional[bool] = None,
    timeout: Optional[int] = None,
    verify: bool = False,
    referrer: Optional[str] = None
) → bool

Set up W&B login credentials.

By default, this will only store credentials locally without verifying them with the W&B server. To verify credentials, pass verify=True.

Args:

• anonymous: Set to “must”, “allow”, or “never”. If set to “must”, always log a user in anonymously. If set to “allow”, only create an anonymous user if the user isn’t already logged in. If set to “never”, never log a user anonymously. Default set to “never”.
• key: The API key to use.
• relogin: If true, will re-prompt for API key.
• host: The host to connect to.
• force: If true, will force a relogin.
• timeout: Number of seconds to wait for user input.
• verify: Verify the credentials with the W&B server.
• referrer: The referrer to use in the URL login request.

Returns:

• bool: If key is configured

Raises:

• AuthenticationError: If api_key fails verification with the server.
• UsageError: If api_key cannot be configured and no tty.

6 - restore()

function restore

restore(
    name: 'str',
    run_path: 'str | None' = None,
    replace: 'bool' = False,
    root: 'str | None' = None
) → None | TextIO

Download the specified file from cloud storage.

File is placed into the current directory or run directory. By default, will only download the file if it doesn’t already exist.

Args:

• name: The name of the file.
• run_path: Optional path to a run to pull files from, i.e. username/project_name/run_id if wandb.init has not been called, this is required.
• replace: Whether to download the file even if it already exists locally
• root: The directory to download the file to. Defaults to the current directory or the run directory if wandb.init was called.

Returns: None if it can’t find the file, otherwise a file object open for reading.

Raises:

• wandb.CommError: If W&B can’t connect to the W&B backend.
• ValueError: If the file is not found or can’t find run_path.

7 - setup()

function setup

setup(settings: 'Settings | None' = None) → _WandbSetup

Prepares W&B for use in the current process and its children.

You can usually ignore this as it is implicitly called by wandb.init().

When using wandb in multiple processes, calling wandb.setup() in the parent process before starting child processes may improve performance and resource utilization.

Note that wandb.setup() modifies os.environ, and it is important that child processes inherit the modified environment variables.

See also wandb.teardown().

Args:

• settings: Configuration settings to apply globally. These can be overridden by subsequent wandb.init() calls.

Example:

import multiprocessing

import wandb


def run_experiment(params):
   with wandb.init(config=params):
        # Run experiment
        pass


if __name__ == "__main__":
   # Start backend and set global config
   wandb.setup(settings={"project": "my_project"})

   # Define experiment parameters
   experiment_params = [
        {"learning_rate": 0.01, "epochs": 10},
        {"learning_rate": 0.001, "epochs": 20},
   ]

   # Start multiple processes, each running a separate experiment
   processes = []
   for params in experiment_params:
        p = multiprocessing.Process(target=run_experiment, args=(params,))
        p.start()
        processes.append(p)

   # Wait for all processes to complete
   for p in processes:
        p.join()

   # Optional: Explicitly shut down the backend
   wandb.teardown()

8 - sweep()

function sweep

sweep(
    sweep: Union[dict, Callable],
    entity: Optional[str] = None,
    project: Optional[str] = None,
    prior_runs: Optional[List[str]] = None
) → str

Initialize a hyperparameter sweep.

Search for hyperparameters that optimizes a cost function of a machine learning model by testing various combinations.

Make note the unique identifier, sweep_id, that is returned. At a later step provide the sweep_id to a sweep agent.

See Sweep configuration structure for information on how to define your sweep.

Args:

• sweep: The configuration of a hyperparameter search. (or configuration generator). If you provide a callable, ensure that the callable does not take arguments and that it returns a dictionary that conforms to the W&B sweep config spec.
• entity: The username or team name where you want to send W&B runs created by the sweep to. Ensure that the entity you specify already exists. If you don’t specify an entity, the run will be sent to your default entity, which is usually your username.
• project: The name of the project where W&B runs created from the sweep are sent to. If the project is not specified, the run is sent to a project labeled ‘Uncategorized’.
• prior_runs: The run IDs of existing runs to add to this sweep.

Returns:

• sweep_id: str. A unique identifier for the sweep.

9 - teardown()

function teardown

teardown(exit_code: 'int | None' = None) → None

Waits for W&B to finish and frees resources.

Completes any runs that were not explicitly finished using run.finish() and waits for all data to be uploaded.

It is recommended to call this at the end of a session that used wandb.setup(). It is invoked automatically in an atexit hook, but this is not reliable in certain setups such as when using Python’s multiprocessing module.