> ## Documentation Index
> Fetch the complete documentation index at: https://wb-21fd5541-style-guide-models-runs-20260604-113608.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Initialize runs

> Initialize W&B runs with wandb.init() to start tracking experiments, including handling concurrent runs in one process.

Initialize a W\&B run with [`wandb.init()`](/models/ref/python/functions/init) to start tracking an experiment and stream metrics, logs, and artifacts to W\&B. This page explains how to initialize a single run and how to manage multiple runs from the same Python process.

By default, W\&B supports one active run per Python process. If you call `wandb.init()` while a run is active, W\&B either returns the active run or finishes it before creating a new one. The behavior depends on the environment and the `reinit` configuration.

To manage multiple active runs in one process, see [Multiple runs in one process](/models/runs/initialize-run#multiple-runs-in-one-process).

<Note>
  W\&B recommends using a context manager (`with` block) when calling `wandb.init()`. This ensures that W\&B finishes the run and uploads its data when the block ends.
</Note>

## Single run per process

The following example initializes a run:

```python title="basic.py" theme={null}
import wandb

with wandb.init(entity="nico", project="awesome-project") as run:
    # Your training logic here
```

The code snippet produces output similar to the following:

```text theme={null}
🚀 View run exalted-darkness-6 at:
https://wandb.ai/nico/awesome-project/runs/pgbn9y21
Find logs at: wandb/run-20241106_090747-pgbn9y21/logs
```

In this example, W\&B logs the run `exalted-darkness-6` to the `awesome-project` project under the `nico` entity. W\&B assigns the run the unique ID `pgbn9y21`.

## Multiple runs in one process

Use the `reinit` parameter in `wandb.init()` or `wandb.Settings` to manage multiple runs in one Python process. For example, keep a primary run active while creating short-lived secondary runs for other tasks.

Common use cases include:

* Creating secondary runs for evaluations or subtasks while a primary run remains active.
* Running multiple sub-experiments from one script.
* Logging different tasks or time periods to separate runs from one process.

<Note>
  **Requirements**

  To manage multiple runs in a single Python process, you must have W\&B Python SDK version `v0.19.10` or newer.
</Note>

### `reinit` options

Use the `reinit` parameter to control what happens when you call `wandb.init()` while another run is active. The following table compares available options and common use cases. For the complete parameter definition, see the [`wandb.init()` reference documentation](/models/ref/python/functions/init).

| Option            | Behavior                                                                                                                                                                                                                                                                                                  | Creates a new run? | Use when                                                                                                                            |
| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------- |
| `create_new`      | Creates a new run without finishing existing active runs. W\&B does not assign the new run to the global `wandb.run` variable. Store each returned run object and use it explicitly. See [Manage multiple active runs in one process](/models/runs/initialize-run/#example-multiple-runs-in-one-process). | Yes                | You need multiple active runs in one process, such as a primary run that remains active while you create and finish secondary runs. |
| `finish_previous` | Finishes active runs before creating a new run. This is the default behavior in non-notebook environments.                                                                                                                                                                                                | Yes                | Runs execute sequentially, and each task or phase should have a separate run.                                                       |
| `return_previous` | Returns the most recent unfinished run instead of creating a new one. This is the default behavior in notebook environments.                                                                                                                                                                              | No                 | Repeated calls to `wandb.init()` should continue using the active run.                                                              |

<Note>
  W\&B doesn't support `create_new` mode for [W\&B Integrations](/models/integrations) that assume a single global run, such as Hugging Face Trainer, Keras callbacks, and PyTorch Lightning. If you use these integrations, run each sub-experiment in a separate process.
</Note>

### Configure `reinit`

You can set the `reinit` value in several ways. Choose the option that best fits your workflow:

* Use `wandb.init()` with the `reinit` argument directly:
  ```python theme={null}
  import wandb
  with wandb.init(reinit="<create_new|finish_previous|return_previous>") as run:
      # Your code here
  ```

* Use `wandb.init()` and pass a `wandb.Settings` object to the `settings` parameter. Specify `reinit` in the `Settings` object:

  ```python theme={null}
  import wandb
  with wandb.init(settings=wandb.Settings(reinit="<create_new|finish_previous|return_previous>")) as run:
      # Your code here
  ```

* Use `wandb.setup()` to set the `reinit` option globally for all runs in the current process. This is useful if you want to configure the behavior once and have it apply to all subsequent `wandb.init()` calls in that process.

  ```python theme={null}
  import wandb
  wandb.setup(wandb.Settings(reinit="<create_new|finish_previous|return_previous>"))
  # Your code here
  ```

* Specify the desired value for `reinit` in the environment variable `WANDB_REINIT`. Defining an environment variable applies the `reinit` option to all `wandb.init()` calls.

  ```bash theme={null}
  export WANDB_REINIT="<create_new|finish_previous|return_previous>"
  ```

The following code snippet shows a high-level overview of how to set up W\&B to create a new run each time you call `wandb.init()`:

```python theme={null}
import wandb

wandb.setup(wandb.Settings(reinit="create_new"))

with wandb.init() as experiment_results_run:
    # This run logs the results of each experiment.
    # You can think of this as a parent run that collects results
    with wandb.init() as run:
        # The do_experiment() function logs fine-grained metrics
        # to the given run and returns result metrics that
        # you want to track separately.
        experiment_results = do_experiment(run)

        # After each experiment, log its results to a parent
        # run. Each point in the parent run's charts corresponds
        # to one experiment's results.
        experiment_results_run.log(experiment_results)
```

### Example: Concurrent processes

This example shows how to apply the `reinit="create_new"` option to a realistic workflow that combines a long-lived primary run with short-lived secondary runs.

Suppose you want to create a primary process that remains open for the entire script, while periodically spawning short-lived secondary processes without finishing the primary process. For example, this pattern can be useful if you want to train a model in the primary run, but compute evaluations or do other work in separate runs.

To achieve this, use `reinit="create_new"` and initialize multiple runs. For this example, suppose "Run A" is the primary process that remains open throughout the script, while "Run B1" and "Run B2" are short-lived secondary runs for tasks like evaluation.

The high-level workflow might look like this:

1. Initialize the primary process Run A with `wandb.init()` and log training metrics.
2. Initialize Run B1 (with `wandb.init()`), log data, then finish it.
3. Log more data to Run A.
4. Initialize Run B2, log data, then finish it.
5. Continue logging to Run A.
6. Finish Run A at the end.

The following Python code example demonstrates this workflow:

```python theme={null}
import wandb

def train(name: str) -> None:
    """Perform one training iteration in its own W&B run.

    Using a 'with wandb.init()' block with `reinit="create_new"` ensures that
    this training sub-run can be created even if another run (like our primary
    tracking run) is already active.
    """
    with wandb.init(
        project="my_project",
        name=name,
        reinit="create_new"
    ) as run:
        # In a real script, you'd run your training steps inside this block.
        run.log({"train_loss": 0.42})  # Replace with your real metric(s)

def evaluate_loss_accuracy() -> (float, float):
    """Returns the current model's loss and accuracy.
    
    Replace this placeholder with your real evaluation logic.
    """
    return 0.27, 0.91  # Example metric values

# Create a 'primary' run that remains active throughout multiple train/eval steps.
with wandb.init(
    project="my_project",
    name="tracking_run",
    reinit="create_new"
) as tracking_run:
    # 1) Train once under a sub-run named 'training_1'
    train("training_1")
    loss, accuracy = evaluate_loss_accuracy()
    tracking_run.log({"eval_loss": loss, "eval_accuracy": accuracy})

    # 2) Train again under a sub-run named 'training_2'
    train("training_2")
    loss, accuracy = evaluate_loss_accuracy()
    tracking_run.log({"eval_loss": loss, "eval_accuracy": accuracy})
    
    # The 'tracking_run' finishes automatically when this 'with' block ends.
```

Key points from the previous example:

* `reinit="create_new"` creates a new run each time you call `wandb.init()`.
* You keep references to each run. `wandb.run` doesn't automatically point to the new run created with `reinit="create_new"`. Store new runs in variables such as `run_a` or `run_b1`, and call `.log()` or `.finish()` on those objects as needed.
* You can finish sub-runs whenever you want while keeping the primary run open.
* Finish your runs with `run.finish()` when you're done logging to them. This ensures that W\&B uploads all data and closes the run.

With this pattern in place, the primary run stays open during the script while you create, log to, and finish each secondary run independently.