Install Weights & Biases 0.26.1: The ML Experiment Platform Guide

If your CI pipeline still pins wandb==0.24.0 somewhere, this tutorial is already worth your time – that version was yanked from PyPI and will silently break. More on exactly why, and how to recover, in the Upgrading section below.

This guide covers deploying Weights & Biases – roughly 21.7 million downloads per month on PyPI as of mid-2026 per PyPI stats – at version 0.26.1, the current stable release per the official Python SDK reference. We focus on what actually breaks during install, not what the marketing pages say.

What you’re actually installing

The wandb Python package is a CLI plus an SDK. It talks to a backend – either W&B’s SaaS or a server you run yourself. Three deployment models exist (per the wandb GitHub README): Multi-tenant Cloud (managed in W&B’s GCP North America account), Dedicated Cloud (single-tenant on AWS, GCP, or Azure with isolated network and storage), and Self-Managed on your own cloud or on-prem infrastructure.

This tutorial covers SDK install against the multi-tenant cloud – the default. Same pip install for all three; the difference is just which host URL you point at during login.

System requirements for wandb 0.26.1

Small footprint. Pure-Python at the surface. But it pulls in a Rust-based backend service (wandb-core) and a list of mandatory dependencies, so a few things can go sideways before you even run your first experiment.

Python 3.8? The install won’t error – it’ll just pull a much older SDK silently, and something will fail at runtime. No warning. According to PyPI docs (current as of mid-2026), W&B commits to supporting each minimum Python version for at least six months after its official end-of-life, which is useful for planning but won’t save a project that’s years behind.

Install wandb 0.26.1

One line, inside a virtualenv:

python -m venv .venv
source .venv/bin/activate # Windows: .venvScriptsactivate
pip install --upgrade wandb==0.26.1

Want the extras – AWS, Azure, GCP integrations, sweeps, media support? PEP 508 markers:

pip install "wandb[aws,gcp,azure,sweeps,media,launch]==0.26.1"

The required dependencies (from PyPI package metadata): click, gitpython, packaging, platformdirs, protobuf, pydantic, pyyaml, requests, sentry-sdk, tornado, and typing-extensions. Any of those pinned to incompatible versions in your project? That’s where pip yells – not at wandb itself.

First-time configuration

Two steps. Generate an API key at wandb.ai under Settings, then:

wandb login

Paste the key when prompted. The docs are clear: the key is visible only once at creation – store it in a password manager or environment variable immediately. The CLI writes the credential to ~/.netrc on Unix. To keep credentials off disk entirely:

export WANDB_API_KEY="your-key-here"
export WANDB_MODE="online" # or "offline" for air-gapped runs

CI runners and Kubernetes jobs: never bake the key into the image. Mount it as a secret and read it via WANDB_API_KEY. The CLI’s interactive prompt will hang a non-TTY container indefinitely otherwise – a common silent failure in automated pipelines.

Verify the install in 30 seconds

Two commands. First confirms the CLI is on PATH. Second confirms the SDK can reach the backend:

wandb --version
# wandb, version 0.26.1

python -c "import wandb; run = wandb.init(project='install-check', mode='online'); run.log({'ok': 1}); run.finish()"

A URL to a fresh run page should print. Open it. See “ok: 1” plotted? Done. Command hangs at “Waiting for W&B process to finish…”? Check your firewall – wandb needs outbound HTTPS to api.wandb.ai.

One thing worth pausing on here: what does “offline mode” actually guarantee? The docs say data is written locally and can be synced later – but if your disk fills up mid-run, or the process is killed without flushing, how much do you lose? The answer isn’t documented clearly anywhere, and the behavior likely varies between SDK versions. If offline reliability matters for your setup, test this before production.

The errors you’ll actually hit

Not in any standard tutorial. All from real GitHub issues and community reports.

• ModuleNotFoundError: No module named 'imp' – Python 3.12 removed the imp module. Turns out this surfaces when pip falls back to building wandb from source via setuptools’ build_meta.py (confirmed in GitHub issue #6519, Python 3.12 / Windows 11). Fix: upgrade pip (pip install -U pip) so it picks the prebuilt wheel. Pinning to a wandb release after late 2024 also works – those all have published Python 3.12 wheels.
• -bash: wandb: command not found – your Python’s bin/ directory isn’t on PATH. The fix: activate the virtualenv you installed into, or use python -m wandb.
• Silent permission denied after wandb.init() – almost always your API key belongs to a different team or entity than the project. Run wandb login --relogin and pass the right entity: wandb.init(entity="your-team").
• Self-hosted users on old servers – the docs say SDK 0.25.x drops compatibility with W&B Server versions older than 0.63.0, but the failure mode is generic GraphQL errors, not a clean version-mismatch message. Check your server version before rolling out an SDK upgrade across developer machines.

Upgrading from older versions (and what not to do)

pip install --upgrade wandb

Two version traps. First: wandb 0.24.0 was yanked from PyPI because runs on that version could silently fail to upload data to the cloud – the bug was discovered after release. According to the GitHub releases page, the fix is to upgrade to 0.24.1; any data already written sits in the local .wandb file and can be replayed with wandb sync ./wandb/run-XXXXX. If you pinned 0.24.0 in a requirements.txt and haven’t touched it since, check now.

Second, on the server side: W&B Server 0.78.0 and 0.78.1 were impacted by a critical security regression allowing unauthorized artifact access (per the W&B Server release notes). Install 0.78.2 before anything else if you’re self-hosting on those versions.

Why does W&B yank versions rather than just issuing a patch advisory? The SDK writes experiment data to local cache files before flushing to the cloud. Once a buggy version has written broken state locally, a new install can’t retroactively fix that state – only wandb sync against the raw .wandb file can. Making the bad version uninstallable stops new users from walking into the same hole.

Uninstall and cleanup

pip uninstall wandb wandb-core wandb-workspaces

# Credentials
rm ~/.netrc # or edit out just the api.wandb.ai entry

# Local run cache (can be several GB)
rm -rf ~/.cache/wandb
rm -rf ./wandb # repeat in each project directory

The ./wandb directory is where offline runs and local .wandb sync files live. Switching accounts? Delete these first – stale run IDs cause 403s on the new account.

FAQ

Is wandb actually free?

For personal accounts and academic use, yes. Team and enterprise tiers have seat-based pricing on the official pricing page – which changes periodically, so check there rather than any third-party summary.

How does this compare to MLflow or Comet?

Same category, different defaults. MLflow runs entirely on your infra out of the box; wandb’s hosted version ships a more polished UI and moves faster on features, but assumes you’re okay sending training data to W&B’s cloud unless you pay for self-hosted. One practical rule: if your security team won’t approve egress to a third-party API, MLflow wins by default. If dashboards and collaboration matter more than data residency, wandb is the faster path.

What happens if my training script crashes mid-run?

The run is marked “crashed” in the UI. Whatever data made it upstream before the crash stays there. The rest – anything unflushed – sits in ./wandb/run-*/ on disk. Push it with wandb sync wandb/offline-run-XXXXX. One less-obvious note: since a recent SDK update, sweep agents now exit cleanly when a sweep is deleted rather than spinning on 404 errors indefinitely, so a crash during a sweep no longer necessarily means a hung agent process to kill manually.

Next step: open your verification run from earlier, click the gear icon, and turn on email notifications for runs longer than 10 minutes. That one setting catches more silent failures than most teams realize.