TimesFM 3.0: Google's Time Series Foundation Model, and the Licence Line That Splits It in Two

What TimesFM is for, and who should care

TimesFM is a pretrained time-series foundation model developed by Google Research for time-series forecasting. The problem it addresses is the cost of building a forecaster per series. Classical approaches require you to fit a model for each series, tune it, and refit as data changes. TimesFM instead ships a checkpoint trained across many series, and you pass new series to it at inference time. The README frames the value as zero-shot generalist capability, and version 3.0 adds native multivariate forecasting plus covariate support for past-only and past-and-future dynamic covariates. The intended user is an engineer or analyst with a batch of numeric series and a horizon, who wants point forecasts and quantiles without a training pipeline. It is less suited to someone who needs a single heavily customised model with domain features baked in.

Inside the decoder-only architecture and what version 3.0 changed

The model is decoder-only, which is the framing of the ICML 2024 paper linked from the README. The repository does not restate the full architecture in the README text, so the paper is the place to read the design. What the README does describe is the version history and how it changes the interface. TimesFM 2.5 uses 200M parameters, down from 500M in 2.0, supports up to 16k context length against 2048 before, adds continuous quantile forecasts up to a 1k horizon through an optional 30M quantile head, and removes the frequency indicator. Version 3.0 moves further: multivariate forecasting and covariates are now native rather than bolted on, and the README claims top rank across fev-bench, the TIME Benchmark and GIFT-Eval. Treat those rankings as the project's own claim, not an independent measurement. The removal of the frequency indicator in 2.5 is the kind of change that quietly breaks older calling code, and the repository keeps 1.0 and 2.0 code archived in a v1 subdirectory for that reason.

Installing TimesFM and running a first forecast

The README gives two install paths. The PyPI route pulls the package with an extra that selects your backend: torch for PyTorch, or mlx for MLX-native inference on Apple silicon, which the README says needs no PyTorch.

# Install TimesFM with PyTorch
pip install timesfm[torch]

# Or, for MLX-native inference on Apple silicon (no PyTorch required)
pip install timesfm[mlx]

For a local checkout, the README uses uv for the virtual environment and installs the package in editable mode. Run these from the repository root after cloning, and you should end up with the timesfm package importable inside .venv.

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

The first real use is univariate forecasting over a batch of arrays with different lengths. The README's TimesFM 3.0 example builds a ModelConfig pointing at the google/timesfm-3.0-pytorch checkpoint, constructs a TimesFM3Evaluator, and calls predict_batch with a horizon and return_quantiles set to True. Note the import path: the example imports from timesfm3, not from timesfm.

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))

According to the README, each output carries a forecast array shaped (12,) for the horizon and a quantiles array shaped (12, 9), covering the 0.1 to 0.9 quantiles. If you see those shapes printed, the checkpoint loaded and the batch ran. The package requires Python 3.10 or newer, per pyproject.toml.

The licence split between code and weights

This is the part most readers will skim past, and it is the one that decides whether TimesFM is usable for them. The repository states that the source code is licensed under Apache-2.0, and that model weights up to version 2.5 remain Apache-2.0. TimesFM 3.0 pretrained weights are distributed under a separate timesfm-non-commercial-license-v1.0 licence and are restricted to non-commercial, non-production use. The README says commercial or production use of the default pretrained weights is not permitted. So the code and the newest weights are governed differently, and pip install timesfm[torch] does not by itself settle which weights you are entitled to run. The README also notes that this open version is not an officially supported Google product, while pointing to BigQuery ML, Google Sheets and Vertex Model Garden as the places TimesFM appears inside Google's own products. That sentence is worth reading twice: the supported route and the open route are not the same thing. Nothing here is legal advice; read the licence text itself before shipping anything.

Where TimesFM is the wrong tool

Three cases stand out. First, commercial production forecasting on the default 3.0 weights, which the licence forbids outright. Second, short or sparse series: a foundation model earns its keep by transferring patterns from pretraining, and a series with a handful of observations gives it little to work with. The README does not document a minimum context length per series, so you would have to establish that boundary yourself. Third, anything needing a guaranteed interface: the project has moved from 1.0 to 2.0 to 2.5 to 3.0 in roughly a year, dropped the frequency indicator along the way, and changed the import surface for 3.0. The README does not document a deprecation policy or a rollback path for checkpoints, and the v1 subdirectory exists precisely because old code had to be parked somewhere. If your pipeline cannot absorb an import change, pin your version and expect to revisit it. There is also a hardware constraint: the torch extra needs torch>=2.0.0 and the flax and xreg extras pull jax[cuda], so the backend you pick determines your machine.

TimesFM against classical forecasting libraries

The natural comparison is with fitted statistical or gradient-boosted forecasters, where you train per series or per group. The difference in approach is where the learning happens. A fitted forecaster learns from your history and nothing else, so a series with two years of weekly data gives it two years of signal. TimesFM moves that learning into pretraining and treats your series as inference input, which is why the README can describe it as a zero-shot generalist and why it can forecast a series it has never seen. The trade is control. With a fitted model you can add regressors and inspect coefficients; with TimesFM you get point forecasts and quantiles, and covariates enter through the mechanisms the model supports, with XReg added back for TimesFM 2.5 in October 2025. If your series are numerous, short and heterogeneous, the pretrained route is attractive. If you have one long series and a strong domain model, a fitted approach will likely beat it and cost less to reason about.

Maintenance, upgrades and what the release cadence costs you

The last push to the repository was on 2026-09-09, and the most recent release is v3.0.0 from 2026-08-28, following v2.0.2 in July 2026 and v2.0.1 in June 2026. That is a fast cadence, and it has a price: the README itself tells readers that 1.0 and 2.0 code is archived in the v1 subdirectory and that pip install timesfm==1.3.0 loads the older package. So the upgrade path is not a single package that spans every checkpoint. If you standardise on 2.5, note that the README lists completed work including a Flax version for faster inference, covariate support via XReg, a LoRA fine-tuning example under timesfm-forecasting/examples/finetuning/, and unit tests in tests/. If you standardise on 3.0, you take the newer capabilities and the non-commercial weight licence together. pyproject.toml declares version 3.0.2 and requires Python 3.10 or newer, so pinning is straightforward. What the README does not document is a support window for any given checkpoint.

Editorial conclusion

Adopt TimesFM if you need zero-shot forecasts over many series without training a model per series, and you can install it with pip install timesfm[torch] on Python 3.10 or newer. Do not adopt it if you need commercial production use of the default weights, since the repository states that TimesFM 3.0 pretrained weights are restricted to non-commercial, non-production use and that commercial or production use is not permitted. Before committing, verify three things: which checkpoint you will load (weights up to 2.5 remain Apache-2.0), whether your hardware matches the torch, mlx, flax or xreg extra, and whether your horizon and covariate needs are met by the model rather than by XReg. The licence boundary, not the model quality, is the first decision here.

Frequently asked questions

Official sources

1. google-research/timesfm on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases