TimesFM: Google's Time Series Foundation Model, and the Licence Split at Version 3.0

The forecasting problem TimesFM is aimed at

Most forecasting code in production is per-series: you pick a model class, fit it to one product's demand history or one sensor's readings, tune it, and repeat. That works when you have a handful of well-understood series and enough history to fit each one. It breaks down when the series count runs into the thousands, when many of them are short, or when new series appear with no history at all. TimesFM is built for that second situation. It is a pretrained foundation model, so the README's framing is zero-shot generalist forecasting: you pass in context windows and get forecasts back without training on your data. The repository positions it for batch forecasting across many series rather than for squeezing accuracy out of one. The README also notes that the open version is not an officially supported Google product, which matters if you were expecting an SLA. The supported commercial routes named in the README are separate: BigQuery ML, Google Sheets, and Vertex Model Garden.

What changed in TimesFM 3.0, and what 2.5 already did

Version 3.0, released August 2026, adds native multivariate forecasting and covariate support, covering both past-only and past-and-future dynamic covariates, described in the README as working without per-task tuning. That is the substantive change: earlier versions were univariate. The 2.5 release, from September 2025, is where several practical properties were set. It uses 200M parameters against 2.0's 500M, supports up to 16k context length against 2048, adds a continuous quantile forecast up to a 1k horizon through an optional 30M quantile head, and removes the frequency indicator that earlier versions required. So the migration story is not only about accuracy. Dropping the frequency flag removes a piece of per-series metadata you previously had to supply correctly. A 16k context is roughly eight times the 2.0 window, which changes what counts as a usable history. The README's benchmark claims for 3.0 (rank #1 on fev-bench, TIME, and GIFT-Eval) are the project's own reported results; treat them as a starting hypothesis for your data, not a substitute for a backtest.

The mechanism: a decoder-only model over patched context

The paper title in the README is explicit: a decoder-only foundation model for time-series forecasting. The architecture follows the language-model pattern rather than the encoder-decoder pattern used by many sequence models. In practice that means the model consumes a context window and emits the continuation, and the Python surface reflects it. In the 3.0 example, you construct a ModelConfig with a checkpoint path, a per_core_batch_size, and a device, wrap it in a TimesFM3Evaluator, and call predict_batch. You pass a list of 1D NumPy arrays and a horizon, and you get back objects carrying a forecast array and, when return_quantiles is set, a quantiles array. The example uses two series of different lengths, 100 and 72 steps, to show that variable-length input is accepted. Note the output shapes in that example: a horizon of 12 returns a forecast of shape (12,) and quantiles of shape (12, 9), the nine quantiles running from 0.1 to 0.9. The predict_batch call also takes use_symmetric_averaging, a flag whose effect the README does not explain; if you rely on it, read the source rather than guessing. For Apple silicon there is an MLX backend that mirrors the PyTorch TimesFM3Forecaster interface and supports univariate or multivariate input with past-only and past-future covariates.

Installing TimesFM and loading a checkpoint

The README gives two PyPI paths, distinguished by backend. For PyTorch, pip install timesfm[torch]. For MLX-native inference on Apple silicon, with no PyTorch required, pip install timesfm[mlx]. For a local checkout, the documented sequence is git clone, cd into the directory, then create a virtual environment and install in editable mode with the torch extra. The README shows uv for this: uv venv, source .venv/bin/activate, then uv pip install -e .[torch]. The 3.0 code path imports from timesfm3, not timesfm, and the checkpoint is named as google/timesfm-3.0-pytorch in the ModelConfig. Older checkpoints live elsewhere in the tree: 2.5 code is under src/timesfm, and 1.0 and 2.0 code is archived in a subdirectory called v1. To load those older models the README points at pip install timesfm==1.3.0. That version pin is the detail most likely to bite you, because the current PyPI package and the archived code under v1 are not interchangeable. The README also records that PyPI was updated to timesfm=2.0.2 in July 2026, so the package version and the model version you intend to run are two separate decisions.

The licence split between code and weights

This is the part to read before anything else. The README states that the source code in the repository is 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, restricted to non-commercial, non-production use. The README's own wording is that commercial or production use of the default pretrained weights is not permitted. The practical consequence is that the permissive licence on the code tells you very little about what you may deploy. Fine-tuning does not obviously resolve this: the README documents a LoRA fine-tuning example using HuggingFace Transformers and PEFT, but it does not state that a fine-tuned derivative of the 3.0 weights escapes the weight licence. If your use is commercial, the safe reading is to stay on 2.5 weights or take one of the hosted routes the README names. This is a description of what the repository says, not legal advice; get your own review before shipping.

Where TimesFM is the wrong tool

The clearest failure mode is not a bug, it is a licence boundary. A commercial forecasting product loading the default 3.0 checkpoint is outside the stated terms. The second is scope. TimesFM is a generalist model; if you have one series with a decade of clean history and a known seasonal structure, a fitted statistical or gradient-boosted model with your own features will usually be easier to explain to whoever signs off on the numbers, and it carries no weight licence at all. The third is cost shape. A foundation model pays off through amortisation across many series, and the README's own batching parameter, per_core_batch_size, is a reminder that throughput depends on how you feed it. If your workload is a few dozen series refreshed hourly, the inference overhead may not be repaid. Fourth, the documentation has gaps that matter for production: the README does not describe memory requirements, expected latency, or how the quantile head behaves at horizons beyond the stated 1k bound. The 3.0 example itself is short, and the MLX section is truncated mid-sentence, so the claim that MLX is numerically matched to PyTorch cannot be fully verified from the README alone.

How TimesFM differs from the obvious alternatives

The nearest comparison is not another library but a different method. A per-series pipeline built on something like statsmodels or a gradient-boosted forecaster fits parameters to your data and lets you inspect them. TimesFM fits nothing at inference time; it applies pretrained weights to a context window. That is the whole trade: you give up per-series interpretability and the ability to inject domain structure directly, and you get a forecast for a brand-new series with no fitting step. The second comparison is a general sequence model such as a transformer trained on your own history. That route can beat a generalist on a narrow domain, but it requires labelled training data, a training loop, and retraining as the domain drifts, none of which TimesFM asks for. The third is the hosted route inside Google's own stack. BigQuery ML and Vertex Model Garden expose TimesFM without you managing checkpoints or weights, which sidesteps the licence question by moving it into the service terms. If your data already lives in BigQuery, that path is worth pricing against self-hosting before you build anything.

Maintenance, versioning, and upgrade cost

The upgrade surface is wider than a typical library. Three things version independently: the PyPI package, the model checkpoint, and the import path. The 3.0 example imports from timesfm3, while 2.5 code sits under src/timesfm and 1.0 and 2.0 code is archived under v1 behind a pinned pip install timesfm==1.3.0. Moving from 2.5 to 3.0 therefore is not just a version bump; it can mean a different module, a different checkpoint identifier, and a different licence. The 2.5 line also changed behaviour in ways that affect existing code: the frequency indicator was removed, so any pipeline that sets it needs revisiting, and the context length moved from 2048 to 16k, which changes memory behaviour even when your code is unchanged. The repository has an active release cadence, with 2.0.1, 2.0.2, and 3.0.0 all appearing within roughly three months in the supplied release list, so pinning both the package version and the checkpoint path is the minimum discipline. The README credits community contributions for the AGENTS file, the SKILL.md under timesfm-forecasting, the fine-tuning example, and unit tests under tests, which suggests the peripheral tooling moves faster than the core model documentation.

Editorial conclusion

Adopt TimesFM if you need zero-shot forecasts over many short or irregular series and can work inside the 3.0 weight licence, or if you can stay on 2.5 weights under Apache-2.0. Do not adopt it for a production commercial system on the default 3.0 checkpoint, because the repository states that commercial or production use of those weights is not permitted. Before committing, verify three things: which licence covers the exact checkpoint you intend to load, whether your series are long enough to benefit from a 16k context rather than a per-series model, and whether the MLX or PyTorch backend matches your hardware, since the README presents them as separate install extras.

Official sources

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