Migrating from Neptune to Weights & Biases

With Neptune officially shutting down on March 5, 2026, it is crucial to begin the data migration process promptly to avoid losing valuable experiment history. The primary goal is to first export all data out of Neptune to local storage, after which you can decide on the import destination. Neptune has provided official resources, including a transition hub and a GitHub repository with the migration scripts, which are the primary source of truth for the export process.

Planning the Migration: Understanding W&B Structure

Before migrating, it’s helpful to understand how Weights & Biases (W&B) organizes entities, which differs slightly from Neptune. The hierarchy in W&B is:

• Organization/Company: The top-level account.
• Teams: Within an organization, you can create multiple teams to group users (e.g., Team A, Team B).
• Projects: Teams own projects, which are collections of experiments.
• Runs: A run is a single experiment within a project. It encapsulates all tracked information: metrics, model checkpoints, datasets, metadata, and media (images, videos, tables).

The Model Registry, used to track production-ready models and datasets, exists at the Organization level, allowing different teams to access and manage registered assets.

The Two-Step Migration Process

The migration is a two-step command-line process: exporting from Neptune and then importing into W&B.

Prerequisites

1. W&B API Key: Generate this from your W&B account settings (top-right corner -> API key).
2. Neptune API Token: Get this from the Neptune UI (bottom-left corner -> “Get your API token”).
3. Migration Script Repo: Clone the official Neptune GitHub repository containing the migration scripts.
4. Dependencies: Install the required Python packages using uv sync.
5. Environment Variables: Set your W&B and Neptune API keys as environment variables for security.

Step 1: Exporting Data from Neptune

The first step is to run the exporter script. It’s highly recommended to first review your Neptune projects and runs to decide what needs to be migrated. The export process creates local Parquet files, so ensure you have sufficient local storage, especially for large projects.

The basic export command is:

exporter <project_name> --exporter-type <neptune_version> --path <data_path>

You must specify your Neptune version (e.g., neptune2 or neptune3), which can be found in the “About Neptune” section of the UI.

For users with very large amounts of data, a more advanced bash script is available that allows you to filter the export by specific projects, start dates, and end dates to make the process more manageable.

Step 2: Importing Data into Weights & Biases

Once the data is exported locally, you can import it into W&B.

1. Log in to the W&B CLI:

   wandb login
   

2. Run the loader command, specifying your W&B entity (your username or team name) and the path to the exported data:

   loader --wandb-entity <your_team_or_username> --path <data_path>
   

The script will output URLs for each run as it’s being created, allowing you to monitor the import process in real-time.

Special Handling for Rich Media

By default, rich media like images and videos are migrated as W&B Artifacts, meaning they are stored but not directly visualized in the UI’s run overview. To render this media directly in the W&B dashboard:

• Clone a specific W&B-provided repository (different from the main Neptune one).
• Add the --rich flag to the loader command during the import step.

Code-Level API Comparison: Neptune vs. W&B

Refactoring your code to use the W&B SDK involves a few key changes.

• Run Initialization:

  • Neptune: neptune.init_run(...)
  • W&B: wandb.init(project="my-project", entity="my-team", ...)

• Logging Configuration/Hyperparameters:

  • Neptune: run["parameters"] = params
  • W&B: wandb.config.update(params_dict)

• Logging Metrics: Neptune uses an .append() method for each metric. W&B uses a single wandb.log() call with a dictionary, which can be more efficient.

  • Neptune: run["train/loss"].append(loss, step=i)
  • W&B: wandb.log({"train_loss": loss, "accuracy": acc}, step=i)

• Logging Media (Images, Video, etc.): W&B uses specific media objects within the wandb.log() call.

  • Neptune: run["images"].upload(image_path)
  • W&B: wandb.log({"predictions": wandb.Image(image, caption="...")})

• Logging Artifacts (Models, Datasets): W&B has a more structured artifact system.

  • Neptune: run["model"].upload("model.pckl")
  • W&B:

    artifact = wandb.Artifact("my-model", type="model")
    artifact.add_file("model.onnx")
    wandb.log_artifact(artifact)
    

• Ending a Run:

  • Neptune: run.stop()
  • W&B: wandb.finish()

Post-Migration: Analysis and Collaboration in W&B

W&B offers powerful tools for analysis that differ from Neptune’s comparison views.

• Workspaces: Each team member has their own customizable workspace for a project. You can add, remove, and resize panels (e.g., line plots, scatter plots, parameter importance) to create a view tailored to your needs.
• Saved Views: You can save a specific workspace layout as a “Saved View.” This creates a shareable, canonical dashboard for the project that all team members can access, ensuring consistent analysis and reporting.

• Tags:
• Feature
• MLOps
• Python
• Weights & Biases
• Model Registry
• Experiment Tracking
• Neptune
• Migration