# How to Set Up the WeatherNext Environment for Development: Complete Setup Guide

> Set up the WeatherNext development environment efficiently. Follow our complete guide to clone the repo install dependencies and verify your setup for Google DeepMind's weather forecasting model.

- Repository: [Google DeepMind/weathernext](https://github.com/google-deepmind/weathernext)
- Tags: getting-started
- Published: 2026-08-10

---

**To set up the WeatherNext development environment, clone the google-deepmind/weathernext repository, create a Python 3 virtual environment, install the package in editable mode with `pip install -e .`, install JAX for your specific hardware (GPU or TPU), and verify the installation by running `pytest -q weathernext`.**

The google-deepmind/weathernext repository provides a research-grade atmospheric forecasting codebase built on JAX and Xarray. Whether you are running inference on local GPUs or developing on Cloud TPUs, properly configuring your development environment ensures access to the model architectures in [`weathernext/weathernext2/architecture.py`](https://github.com/google-deepmind/weathernext/blob/main/weathernext/weathernext2/architecture.py), checkpoint utilities in [`weathernext/utils/model_utils.py`](https://github.com/google-deepmind/weathernext/blob/main/weathernext/utils/model_utils.py), and cyclone tracking tools.

## Prerequisites and System Requirements

WeatherNext requires **Python 3** and supports both GPU and TPU backends via JAX. The codebase is designed for Linux workstations and Google Colab environments.

### Hardware Backends: GPU vs. TPU

- **GPU Development**: Standard CUDA 12.x compatible wheels work for local workstations. Install using `pip install "jax[cuda12]"` with the JAX CUDA release URL.
- **TPU Development**: Required for Cloud TPU or Colab environments. Install using `pip install "jax[tpu]"` with the libtpu release URL.

## Step-by-Step WeatherNext Environment Setup

### 1. Clone the Repository and Create an Isolated Environment

Create a dedicated virtual environment to avoid conflicts with system packages. Using `venv` or `conda` both work, though the repository documentation emphasizes standard Python environments.

```bash

# Clone the repository

git clone https://github.com/google-deepmind/weathernext.git
cd weathernext

# Create and activate virtual environment

python3 -m venv venv
source venv/bin/activate

```

### 2. Install the Core Package and Dependencies

The repository ships with a [`setup.py`](https://github.com/google-deepmind/weathernext/blob/main/setup.py) that declares dependencies including JAX, NumPy, Xarray, and other scientific libraries. Install in editable mode to enable development changes.

```bash
pip install -e .

```

This command pulls in the core dependencies required by [`weathernext/weathernext2/architecture.py`](https://github.com/google-deepmind/weathernext/blob/main/weathernext/weathernext2/architecture.py) and the utilities in [`weathernext/utils/model_utils.py`](https://github.com/google-deepmind/weathernext/blob/main/weathernext/utils/model_utils.py).

### 3. Configure JAX for Your Hardware

After installing the base package, install the JAX distribution matching your accelerator.

```bash

# For GPU (CUDA 12.x)

pip install "jax[cuda12]" -f https://storage.googleapis.com/jax-releases/jax_cuda_releases.html

# For TPU (Colab or Cloud TPU)

pip install "jax[tpu]" -f https://storage.googleapis.com/jax-releases/libtpu_releases.html

```

### 4. Install Optional Dependencies

If you plan to work with older GraphCast or GenCast models referenced in the codebase, install their respective packages from the DeepMind repositories.

```bash

# Optional: GraphCast support

pip install git+https://github.com/deepmind/graphcast.git

# Optional: GenCast support  

pip install git+https://github.com/deepmind/gencast.git

```

Additionally, install Jupyter for running the demonstration notebooks and `tf-nightly` if utilizing TensorFlow-based utilities within the codebase.

### 5. Verify the Installation

Run the test suite to confirm that JAX, NumPy, and the WeatherNext utilities initialize correctly.

```bash
pytest -q weathernext

```

A successful run indicates that [`weathernext/cyclones/tracker_base.py`](https://github.com/google-deepmind/weathernext/blob/main/weathernext/cyclones/tracker_base.py) and other core modules load without import errors.

## Running Your First Inference

Once the environment is configured, load pre-trained weights from the public Google Cloud bucket and execute an auto-regressive rollout. The `load_checkpoint` and `init_state` functions in [`weathernext/utils/model_utils.py`](https://github.com/google-deepmind/weathernext/blob/main/weathernext/utils/model_utils.py) handle checkpoint fetching and state initialization.

```python
import jax
import weathernext.weathernext2.architecture as wn2
from weathernext.utils.model_utils import load_checkpoint, init_state

# Load pre-trained weights (e.g., Mini model)

ckpt_url = "gs://weather-next-bucket/WeatherNextCyclones_Mini_2024.npz"
params = load_checkpoint(ckpt_url)

# Initialize state with random keys

rng = jax.random.PRNGKey(0)
state = init_state(rng, params)

# Run single auto-regressive step defined in architecture.py

next_state = wn2.autoregressive_step(state, params)
print("Forecast step completed, shape:", next_state.fields.shape)

```

## Key Source Files for Developers

Understanding the repository structure helps navigate the development environment:

- **[`setup.py`](https://github.com/google-deepmind/weathernext/blob/main/setup.py)**: Declares Python package dependencies and entry points used during `pip install`.
- **`docs/weathernext2/wn2_demo.ipynb`**: Interactive Colab notebook demonstrating end-to-end inference, cyclone tracking, and visualization.
- **[`weathernext/weathernext2/architecture.py`](https://github.com/google-deepmind/weathernext/blob/main/weathernext/weathernext2/architecture.py)**: Core model definition containing `autoregressive_step` and network architectures.
- **[`weathernext/utils/model_utils.py`](https://github.com/google-deepmind/weathernext/blob/main/weathernext/utils/model_utils.py)**: Implements `load_checkpoint()`, `init_state()`, and TPU-compatible sharding helpers.
- **[`weathernext/cyclones/tracker_base.py`](https://github.com/google-deepmind/weathernext/blob/main/weathernext/cyclones/tracker_base.py)**: Base implementation for the direct cyclone tracker used in demonstration workflows.
- **[`CONTRIBUTING.md`](https://github.com/google-deepmind/weathernext/blob/main/CONTRIBUTING.md)**: Guidelines for code style, testing requirements, and CI workflows when submitting changes.

## Summary

- Clone **google-deepmind/weathernext** and create a Python virtual environment to isolate dependencies.
- Install the package in editable mode with `pip install -e .` using the provided [`setup.py`](https://github.com/google-deepmind/weathernext/blob/main/setup.py).
- Install **JAX** with CUDA 12 support for GPUs or TPU support for Cloud TPU/Colab environments.
- Verify functionality by running `pytest -q weathernext` to test the installation.
- Use **[`weathernext/utils/model_utils.py`](https://github.com/google-deepmind/weathernext/blob/main/weathernext/utils/model_utils.py)** for checkpoint loading and **`docs/weathernext2/wn2_demo.ipynb`** for reference implementations.

## Frequently Asked Questions

### Do I need a TPU to run WeatherNext?

No. While the codebase supports TPU acceleration via `jax[tpu]`, it runs efficiently on NVIDIA GPUs with CUDA 12 using the `jax[cuda12]` wheels. The `docs/weathernext2/wn2_demo.ipynb` notebook works on both local GPU workstations and Colab TPU runtimes.

### What Python version is required for WeatherNext?

The repository requires **Python 3** and follows standard scientific Python packaging. The [`setup.py`](https://github.com/google-deepmind/weathernext/blob/main/setup.py) file specifies exact dependency versions compatible with JAX 0.4.x and NumPy 1.24+ for numerical stability.

### How do I load pre-trained model weights?

Use the `load_checkpoint()` function from [`weathernext/utils/model_utils.py`](https://github.com/google-deepmind/weathernext/blob/main/weathernext/utils/model_utils.py), which automatically fetches weights from Google Cloud Storage URLs (e.g., `gs://weather-next-bucket/WeatherNextCyclones_Mini_2024.npz`) and handles deserialization.

### Where can I find the official demo notebook?

The official demonstration notebook is located at `docs/weathernext2/wn2_demo.ipynb` in the repository root. You can open it directly in Google Colab via the GitHub integration or run it locally after completing the environment setup.