google-research/timesfm

What it is

TimesFM is a decoder-only foundation model from Google Research for time-series forecasting. Rather than training a model per series, it performs zero-shot forecasting on new numeric sequences, and the 3.0 release adds native multivariate targets and covariate support for past-only and past-and-future channels. The work is published at ICML 2024 and described in the project's paper and research blog.

The repository is for practitioners who need forecasts from raw arrays without per-task tuning: data scientists, analysts, and engineers building forecasting services. Code lives under the Python package, with checkpoints on Hugging Face and archived 1.0/2.0 code under v1.

Install and run

The PyPI package is the shortest path. The torch extra pulls in PyTorch, while the mlx extra targets Apple silicon without PyTorch:

pip install timesfm[torch]

Then load the 3.0 checkpoint and forecast a batch of series with optional quantiles:

import numpy as np
from timesfm3 import TimesFM3Evaluator, ModelConfig

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

ts1 = np.linspace(0, 1, 100).astype(np.float32)
ts2 = np.sin(np.linspace(0, 24, 72)).astype(np.float32)
outputs = list(forecaster.predict_batch(
    [ts1, ts2], horizon=12, return_quantiles=True, use_symmetric_averaging=False
))
print(outputs[0].forecast.shape)   # (12,)
print(outputs[0].quantiles.shape)  # (12, 9)

A local editable install with uv venv and uv pip install -e .[torch] is documented for development against the repository source. For multivariate forecasting, pass a 2D array shaped (num_variates, context_length) plus covariate arrays to predict_batch; the examples show the argument names and expected output shapes.

On Apple silicon, the MLX backend mirrors the PyTorch interface and can be loaded with TimesFM3Forecaster.from_pretrained("google/timesfm-3.0-pytorch"). It accepts univariate or multivariate input and covariates, and the README reports numerical agreement with the PyTorch path at specific error tolerances.

Constraints

TimesFM 3.0 pretrained weights are not Apache-2.0. The source code is Apache-2.0 and weights through 2.5 remain Apache-2.0, but 3.0 weights use a separate non-commercial license that forbids downloaded or self-hosted commercial and production use. Commercial use of 3.0 is offered through Google Cloud services such as BigQuery ML, governed by Google Cloud terms.

PyTorch is required for the CUDA path; the MLX path is limited to Apple silicon. The default 3.0 model has 200M parameters and supports 16k context, whereas 2.5 documents up to 16k context and an optional quantile head for horizons up to 1k. The README states the open version is not an officially supported Google product.

HotRepo's take

The project has accumulated roughly 35k stars and 3.4k forks. A daily snapshot on 2026-09-03 recorded +1,626 stars, and on 2026-11-05 it held position 12 on the Python daily list with +55 stars in that snapshot. Those figures span different dates and list scopes, so they do not establish a trend; the single Python daily rank is the only recorded ranking here.

The Hacker News threads show sustained interest, with the March 2026 post reaching 327 points and 109 comments. Much of the discussion questions whether one general model can handle heterogeneous series such as egg prices and inflation, and a reply points out that such models primarily capture trend, seasonality, and residuals rather than external events (discussion). That framing is worth keeping in mind when evaluating zero-shot forecasts: benchmark leadership does not remove the need to check whether the model's learned patterns match a given domain. The license split also deserves attention before adopting 3.0, since the code is open but the current weights are non-commercial.