# How to Load the TimesFM 2.5 Model with PyTorch: A Complete Guide

> Learn to load the TimesFM 2.5 model with PyTorch. Import TimesFM_2p5_200M_torch, use from_pretrained to download the checkpoint, and compile for efficient inference.

- Repository: [Google Research/timesfm](https://github.com/google-research/timesfm)
- Tags: how-to-guide
- Published: 2026-04-02

---

**Load the TimesFM 2.5 model by importing `TimesFM_2p5_200M_torch` from [`src/timesfm/timesfm_2p5/timesfm_2p5_torch.py`](https://github.com/google-research/timesfm/blob/main/src/timesfm/timesfm_2p5/timesfm_2p5_torch.py) and calling `from_pretrained()` to download the 200M‑parameter checkpoint from Hugging Face, then compile it with a `ForecastConfig` before running inference.**

The `google-research/timesfm` repository provides a native PyTorch implementation of TimesFM 2.5, a 200‑million‑parameter foundation model for time‑series forecasting. Unlike the JAX implementation, the PyTorch version inherits from `PyTorchModelHubMixin`, enabling seamless weight loading via the Hugging Face Hub using Safetensors format. This guide demonstrates how to load the TimesFM 2.5 model with PyTorch, configure inference parameters, and execute forecasts on your data.

## Importing the PyTorch Wrapper Class

The PyTorch interface resides in **[`src/timesfm/timesfm_2p5/timesfm_2p5_torch.py`](https://github.com/google-research/timesfm/blob/main/src/timesfm/timesfm_2p5/timesfm_2p5_torch.py)**. The primary class **`TimesFM_2p5_200M_torch`** wraps the low‑level transformer implementation and adds Hugging Face Hub integration.

```python
from timesfm.timesfm_2p5.timesfm_2p5_torch import TimesFM_2p5_200M_torch
from timesfm.configs import ForecastConfig
import numpy as np

```

This wrapper bundles the underlying **`TimesFM_2p5_200M_torch_module`** and exposes high‑level methods for checkpoint loading and batched decoding.

## Loading Pre‑Trained Weights

### Downloading from Hugging Face Hub (Default)

The class inherits **`from_pretrained()`** from `PyTorchModelHubMixin`. Calling this method with no arguments automatically pulls the default **`google/timesfm-2.5-200m-pytorch`** repository (~1 GB download) and caches the weights locally.

```python

# Auto-detects CUDA and moves model to GPU if available

model = TimesFM_2p5_200M_torch.from_pretrained()

```

The loader specifically looks for **`model.safetensors`** (referenced internally via `TimesFM_2p5_200M_torch.WEIGHTS_FILENAME`) and deserializes it into the PyTorch module. The underlying `TimesFM_2p5_200M_torch_module.load_checkpoint` automatically detects CUDA availability via `torch.cuda.is_available()` and moves parameters to the GPU without manual device mapping.

### Loading a Local Safetensors Checkpoint

If you have pre‑downloaded the weights, point `from_pretrained()` to the local directory containing `model.safetensors`:

```python
model = TimesFM_2p5_200M_torch.from_pretrained(model_id="/path/to/local/dir")

```

The wrapper resolves the path and loads the Safetensors file directly from disk, bypassing the Hugging Face download.

## Configuring and Compiling the Model

Before inference, you must **compile** the model with a **`ForecastConfig`** that defines memory constraints and decoding behavior. This step builds an optimized decode function based on your specific context length, horizon, and batch size.

```python
forecast_cfg = ForecastConfig(
    max_context=4096,          # Maximum input time steps the model observes

    max_horizon=128,           # Maximum prediction steps per forward pass

    per_core_batch_size=1,     # Batch size per GPU/CPU core for decoding

    normalize_inputs=True,     # Enable reversible normalization (recommended)

    return_backcast=False,     # Set True to receive backcast outputs

)

model.compile(forecast_cfg)

```

The `compile()` method configures internal caches and JIT‑compatible decoding paths according to the `TransformerConfig` embedded in the forecast configuration. Skipping this step results in uninitialized inference graphs.

## Executing Inference

### Input Data Format

The `forecast()` method expects a **list of 1‑D NumPy arrays**. Each series represents a univariate time series of arbitrary length (up to `max_context`).

```python

# Example: two synthetic series of 300 points each

series_a = np.sin(np.linspace(0, 20, 300))
series_b = np.cos(np.linspace(0, 20, 300))
inputs = [series_a, series_b]

```

### Running the forecast() Method

Call `forecast()` with the desired prediction horizon and the prepared inputs. The method returns a tuple containing **point forecasts** and **quantile forecasts**.

```python

# Forecast 96 steps ahead

points, quantiles = model.forecast(horizon=96, inputs=inputs)

print("Point forecasts shape:", points.shape)        # (2, 96)

print("Quantile forecasts shape:", quantiles.shape)  # (2, 96, 10)

```

The output shapes correspond to `(batch_size, horizon)` for point predictions and `(batch_size, horizon, num_quantiles)` for the full distribution, where the model outputs 10 quantile levels by default.

## Accessing the Underlying PyTorch Module

For fine‑tuning or architectural inspection, access the raw PyTorch module via the **`model`** attribute:

```python
torch_mod = model.model
print(torch_mod)          # Displays layer architecture

print(torch_mod.device)   # Confirms 'cuda' or 'cpu'

```

This exposes the complete transformer stack defined in [`src/timesfm/torch/transformer.py`](https://github.com/google-research/timesfm/blob/main/src/timesfm/torch/transformer.py), allowing you to manipulate parameters, freeze layers, or integrate the model into custom training loops.

## Summary

- Import **`TimesFM_2p5_200M_torch`** from [`src/timesfm/timesfm_2p5/timesfm_2p5_torch.py`](https://github.com/google-research/timesfm/blob/main/src/timesfm/timesfm_2p5/timesfm_2p5_torch.py) to access the PyTorch interface.
- Call **`from_pretrained()`** to load the `google/timesfm-2.5-200m-pytorch` checkpoint from Hugging Face Hub or a local Safetensors file.
- **Compile** the model using a **`ForecastConfig`** to set context length, horizon, and batch size constraints before forecasting.
- Pass a **list of 1‑D NumPy arrays** to **`forecast()`** to generate point and quantile predictions.
- Access the raw module via **`model.model`** for advanced modifications; CUDA detection is automatic.

## Frequently Asked Questions

### What is the default model repository for TimesFM 2.5 PyTorch?

When calling `from_pretrained()` without arguments, the class automatically pulls **`google/timesfm-2.5-200m-pytorch`** from the Hugging Face Hub. This repository contains the 200M‑parameter checkpoint stored as `model.safetensors`, totaling approximately 1 GB in size.

### Do I need to manually move the model to CUDA?

No. The internal **`TimesFM_2p5_200M_torch_module.load_checkpoint`** method automatically checks `torch.cuda.is_available()` and transfers the model weights to the GPU when detected. You do not need to call `.to('cuda')` or `.cuda()` manually on the wrapper instance.

### Why must I compile the model before forecasting?

The **`compile()`** method instantiates the decoding cache and builds the inference graph based on your **`ForecastConfig`** parameters (max_context, max_horizon, batch size). Without compilation, the model lacks the initialized state necessary for batched decoding and will raise runtime errors when `forecast()` is called.

### Can I fine-tune the TimesFM 2.5 PyTorch implementation?

Yes. Access the raw PyTorch module through the **`model.model`** attribute to obtain a standard `nn.Module` object compatible with PyTorch optimizers and loss functions. You can then implement custom training loops using the transformer architecture defined in [`src/timesfm/torch/transformer.py`](https://github.com/google-research/timesfm/blob/main/src/timesfm/torch/transformer.py).