# Weights & Biases migration

Choose one of three migration modes based on how much you want to change and how much you want to keep W&B in the loop.

| Mode | Import | Source of truth | Code change |
| --- | --- | --- | --- |
| **Drop-in** | `import instantml.compat.wandb as wandb` | InstantML | One import line |
| **Shadow** | `im.init(..., shadow_wandb=True)` | Both | One init flag |
| **Mirror** | `import instantml.wandb_mirror as wandb` | W&B | One import line |

Before you start, authenticate the SDK with [`instantml login`](/docs/sdk/installation-auth.md) or set `INSTANTML_API_KEY`.

## Use the drop-in replacement

Swap the import to send your existing `wandb` calls straight to InstantML. This mode does **not** require the official `wandb` package — InstantML is the only destination.

```python
import instantml.compat.wandb as wandb

run = wandb.init(
    project="quickstart",
    name="seed-42",
    config={"seed": 42, "lr": 3e-4},
    tags=["baseline"],
)

for step in range(1, 51):
    wandb.log({"train/loss": 1.0 / step, "eval/accuracy": step / 60}, step=step)

wandb.finish()
```

Run the script and the SDK creates a run in your InstantML project — your `wandb.log` calls land as ordinary metrics, charted by step.

Supported: `init`, `log`, `finish`, `config` (including `config.update`), `watch`, `Artifact` / `run.log_artifact`, and using the run as a context manager. `define_metric` is accepted as a no-op.

Unsupported features raise a clear `UnsupportedWandbFeature` error rather than silently dropping data:

- `wandb.sweep(...)` — W&B sweeps are not supported.
- `offline`, `dryrun`, and `disabled` modes (via the `mode=` argument or the `WANDB_MODE` / `WANDB_DISABLED` environment variables) — they would otherwise hide missing logs.
- Extra keyword arguments to `wandb.log(...)`, such as `commit=`.

In drop-in mode the `project` argument targets InstantML directly, and credentials come from your normal InstantML configuration (`instantml login` or `INSTANTML_API_KEY`). The `id`, `group`, and `job_type` arguments are preserved in run metadata; `resume`, `reinit`, `dir`, and `settings` are ignored.

## Shadow W&B alongside InstantML

Keep logging to InstantML and have the SDK send the same scalar metrics to W&B in parallel. Useful while you evaluate InstantML side by side.

Shadow mode needs the official `wandb` package and W&B credentials:

```bash
python -m pip install "instantml[wandb]"
wandb login
```

Pass `shadow_wandb=True` to `im.init(...)`:

```python
import instantml as im

run = im.init(
    project="quickstart",
    name="wandb-shadow-seed-42",
    config={"seed": 42},
    shadow_wandb=True,
)

for step in range(1, 51):
    run.log({"train/loss": 1.0 / step}, step=step)

run.finish()
```

The same run appears in both dashboards: InstantML records it directly, and W&B receives the mirrored project, name, config, tags, and metrics.

`wandb.init()` can take seconds, so it runs on a background thread — InstantML's own init stays fast, and log calls that arrive before W&B is ready are queued in order and drained once it resolves. If `wandb` is not installed or `wandb.init(...)` fails, InstantML warns, disables the shadow, and keeps logging to InstantML.

### Point the shadow at a different W&B project

`shadow_wandb=True` mirrors the project, name, config, tags, and notes from your InstantML `init` call, and W&B reads its own environment (`WANDB_API_KEY`, `WANDB_ENTITY`) for auth. Pass a `dict` instead and it goes straight through as `wandb.init(**dict)`, so you can override the W&B project or entity independently:

```python
run = im.init(
    project="quickstart",
    shadow_wandb={"project": "instantml-pilot", "entity": "my-team"},
)
```

### Attach to an existing wandb.Run

Pass an already-constructed `wandb.Run` and the SDK attaches to it and fans out log calls instead of creating a new W&B run:

```python
import wandb
import instantml as im

wandb_run = wandb.init(project="quickstart")
run = im.init(project="quickstart", shadow_wandb=wandb_run)
```

## Mirror into InstantML while W&B stays primary

For the lowest-risk pilot, keep W&B as the source of truth and mirror scalar metrics into InstantML with a one-line import swap. This mode requires the official `wandb` package — W&B still receives every call first.

```python
import instantml.wandb_mirror as wandb

run = wandb.init(
    project="quickstart",
    name="mirror-seed-42",
    config={"seed": 42},
)

for step in range(1, 51):
    wandb.log({"train/loss": 1.0 / step}, step=step)

wandb.finish()
```

The official `wandb` package receives `init`, `log`, and `finish` exactly as before, and any attribute the mirror doesn't wrap passes through to it. InstantML receives a best-effort copy of scalar metrics and config updates. InstantML-side failures warn once and never interrupt the W&B logging path.

By default the mirror uses the same project name on the InstantML side and your normal InstantML credentials. Override either with mirror-specific keyword arguments on `init`:

```python
run = wandb.init(
    project="quickstart",
    instantml_project="wandb-mirror-pilot",
    instantml_api_key="instantml_...",
    instantml_base_url="https://api.instantml.ai",
)
```

> **Note:** The mirror copies finite scalar metrics only. W&B artifacts, media, and `log` calls with extra keyword arguments are not mirrored — they still reach W&B, and the mirror warns once so you know.

## Import past W&B history

To bring your existing experiment history across, run `instantml import wandb` against a W&B export. The same tooling imports Neptune and MLflow data and syncs TensorBoard event files. See [Imports](/docs/guides/imports.md).

## Next steps

- [Import past W&B, Neptune, or MLflow history](/docs/guides/imports.md)
- [Why teams switch: the W&B alternative guide](/docs/guides/wandb-alternative.md)
- [Install and authenticate the SDK](/docs/sdk/installation-auth.md)
- [Run the quickstart](/docs/quickstart.md)
- [Compare runs in the dashboard](/docs/dashboard/compare-runs.md)

## Agent navigation

- [Docs index](/llms.txt)
- [Full docs bundle](/llms-full.txt)

### Get Started

- [Overview](/docs/index.md)
- [Quickstart](/docs/quickstart.md)
- [Core Concepts](/docs/concepts/core-concepts.md)
- [Pricing](/docs/pricing.md)
- [Benchmarks](/docs/benchmarks.md)
- [Examples](/docs/guides/examples.md)
- [Troubleshooting](/docs/troubleshooting.md)

### SDK

- [Installation Auth](/docs/sdk/installation-auth.md)
- [Logging](/docs/sdk/logging.md)
- [Tracing](/docs/sdk/tracing.md)
- [Metrics Steps](/docs/sdk/metrics-steps.md)
- [Config Tags Notes](/docs/sdk/config-tags-notes.md)
- [Artifacts Checkpoints](/docs/sdk/artifacts-checkpoints.md)
- [Rich Objects](/docs/sdk/rich-objects.md)
- [Distributed Training](/docs/sdk/distributed-training.md)
- [Console System Integrations](/docs/sdk/console-system-integrations.md)
- [Reliability](/docs/sdk/reliability.md)
- [Cli Login](/docs/sdk/cli-login.md)
- [Querying Data](/docs/sdk/querying-data.md)
- [Agent Mcp](/docs/sdk/agent-mcp.md)
- [Examples Patterns](/docs/sdk/examples-patterns.md)

### Integrations

- [Overview](/docs/integrations/overview.md)
- [Pytorch Lightning](/docs/integrations/pytorch-lightning.md)
- [Huggingface Transformers](/docs/integrations/huggingface-transformers.md)
- [Keras](/docs/integrations/keras.md)
- [Wandb](/docs/integrations/wandb.md) (current page)

### Dashboard

- [Tour](/docs/dashboard/tour.md)
- [Organizations Workspaces](/docs/dashboard/organizations-workspaces.md)
- [Runs Workspace](/docs/dashboard/runs-workspace.md)
- [Metrics Charts](/docs/dashboard/metrics-charts.md)
- [Run Detail](/docs/dashboard/run-detail.md)
- [Traces](/docs/dashboard/traces.md)
- [Compare Runs](/docs/dashboard/compare-runs.md)
- [Research Dashboards](/docs/dashboard/research-dashboards.md)
- [Artifacts Files](/docs/dashboard/artifacts-files.md)
- [Run Health](/docs/dashboard/alerts.md)
- [Datasets](/docs/dashboard/datasets.md)
- [Checkpoints](/docs/dashboard/checkpoints.md)
- [Reports](/docs/dashboard/reports.md)
- [Settings Api Keys](/docs/dashboard/settings-api-keys.md)
- [Api Tab](/docs/dashboard/api-tab.md)
- [Onboarding Team Billing](/docs/dashboard/onboarding-team-billing.md)

### Data

- [Imports](/docs/guides/imports.md)
- [W&B alternative](/docs/guides/wandb-alternative.md)
- [InstantML vs MLflow](/docs/guides/instantml-vs-mlflow.md)
- [W&B import guide](/docs/guides/wandb-import-guide.md)
- [W&B and Neptune imports](/docs/guides/wandb-neptune-imports.md)
- [Export Usage Limits](/docs/guides/export-usage-limits.md)
- [Pricing Limits Billing](/docs/guides/pricing-limits-billing.md)
- [Auth Billing Storage](/docs/guides/auth-billing-storage.md)
- [Customer Owned Clickhouse](/docs/guides/customer-owned-clickhouse.md)
- [Observability](/docs/guides/observability.md)

### API

**Practical API guides**

- [Authentication](/docs/api/authentication.md)
- [Errors And Limits](/docs/api/errors-and-limits.md)
- [Health Observability](/docs/api/health-observability.md)
- [Projects Runs](/docs/api/projects-runs.md)
- [Metrics Series](/docs/api/metrics-series.md)
- [Attributes Objects](/docs/api/attributes-objects.md)
- [Artifacts](/docs/api/artifacts.md)
- [Reports](/docs/api/reports.md)
- [Iframe Embeds](/docs/api/iframe-embeds.md)
- [Import Export Usage](/docs/api/import-export-usage.md)
- [Dashboard Control State](/docs/api/dashboard-control-state.md)
**Architecture**

- [System Overview](/docs/architecture/system-overview.md)
- [Service Planes](/docs/architecture/service-planes.md)
- [Storage Model](/docs/architecture/storage-model.md)
- [Google Clickhouse](/docs/architecture/google-clickhouse.md)
- [Auth Tenancy](/docs/architecture/auth-tenancy.md)
- [Schema Reference](/docs/architecture/schema-reference.md)

### API Reference

- [API Reference](/docs/api-reference.md)