google-research/timesfm

TimesFM – A Foundation Model for Time‑Series Forecasting

What it is – TimesFM (Time Series Foundation Model) is a Google‑Research‑backed, decoder‑only neural model that has been pretrained on massive collections of time‑series data. It is offered as a ready‑to‑use library (PyPI package timesfm) and as Hugging Face checkpoints, enabling both zero‑shot forecasting and fine‑tuning for custom domains.

Why it matters – Like large language models for text, TimesFM aims to be a general‑purpose forecaster that works out of the box on many kinds of univariate or multivariate series, with or without auxiliary covariates. The authors report state‑of‑the‑art results on the three major time‑series foundation‑model benchmarks (fev‑bench, TIME, GIFT‑Eval).

---

Key capabilities (as of version 3.0)

• Univariate & multivariate forecasting – Predict any number of target series simultaneously.
• Dynamic covariate support – Accept past‑only covariates and past‑and‑future covariates without task‑specific tuning.
• Variable‑length inputs – Batches can contain series of different context lengths.
• Quantile forecasts – Optional output of up to 9 quantiles (0.1‑0.9) for uncertainty estimation.
• Zero‑shot performance – Works well on new datasets without additional training.
• Fine‑tuning via LoRA – Example scripts show how to adapt the model with low‑rank adapters using Hugging Face Transformers + PEFT.
• Scalable deployment – Integrated in Google products (BigQuery ML, Sheets, Vertex Model Garden) and available as a Dockerized endpoint.

---

Getting started

# Install the PyTorch variant from PyPI
pip install "timesfm[torch]"

Or clone the repo and install in editable mode:

git clone https://github.com/google-research/timesfm.git
cd timesfm
uv venv && source .venv/bin/activate
uv pip install -e .[torch]

Quick inference example (univariate)

import numpy as np
from timesfm3 import TimesFM3Evaluator, ModelConfig

cfg = ModelConfig(
    checkpoint_path="google/timesfm-3.0-pytorch",
    per_core_batch_size=32,
    device="cuda",
)
forecaster = TimesFM3Evaluator(cfg)

ts = np.linspace(0, 1, 100).astype(np.float32)   # a simple series
out = forecaster.predict_batch([ts], horizon=12, return_quantiles=True)[0]
print(out.forecast.shape)   # (12,)
print(out.quantiles.shape)  # (12, 9)

Multivariate example with covariates

import numpy as np
from timesfm3 import TimesFM3Evaluator, ModelConfig

cfg = ModelConfig(
    checkpoint_path="google/timesfm-3.0-pytorch",
    per_core_batch_size=16,
    device="cuda",
)
forecaster = TimesFM3Evaluator(cfg)

target = np.random.randn(3, 128).astype(np.float32)          # 3 series
past_cov = np.random.randn(1, 128).astype(np.float32)       # past‑only
future_cov = np.random.randn(2, 152).astype(np.float32)     # past+future
out = forecaster.predict_batch(
    contexts=[target],
    horizon=24,
    past_only_covariates=[past_cov],
    past_future_covariates=[future_cov],
    return_quantiles=True,
)[0]
print(out.forecast.shape)   # (3, 24)
print(out.quantiles.shape)  # (3, 24, 9)

---

Model versions & licensing

Version	Parameters	Context length	Notable changes
1.0 / 2.0	–	–	Original release (archived in v1).
2.5	200 M	16 k	Smaller model, longer context, optional 30 M quantile head, Flax inference, covariate support via XReg.
3.0	– (released as checkpoint)	–	Native multivariate + covariates, best benchmark scores, zero‑shot generalist.

• Source code is Apache‑2.0.
• Pre‑trained weights up to v2.5 are Apache‑2.0. The v3.0 checkpoint is distributed under a separate non‑commercial license (timesfm-non-commercial-license-v1.0), prohibiting commercial or production use.

---

Community & ecosystem

• Fine‑tuning guide – timesfm-forecasting/examples/finetuning/ (LoRA + PEFT).
• Agent integration – AGENTS.md describes how to expose TimesFM as a skill for AI agents.
• Tests – tests/ provide unit coverage for core layers and utilities.
• Contributions – Recent community fixes are acknowledged in the changelog.

---

Bottom line

TimesFM is a genuine, research‑grade foundation model for time‑series forecasting, packaged for easy installation, inference, and adaptation. It is suitable for data scientists and engineers who need a strong, out‑of‑the‑box forecaster and are comfortable with the non‑commercial restriction on the latest weights.