TimesFM: Google's Foundation Model for Time Series, Explained for Developers

TimesFM proposes a different deal: skip the training step entirely. It is a pretrained model from Google Research that forecasts time series it has never seen before. Same idea as an LLM, except instead of predicting the next word, it predicts the next value. You hand it a NumPy array of history, tell it how far ahead to look, and get a forecast back. No training loop, no hyperparameter search. This post covers what it actually does, how the API feels, what landed in the brand-new 3.0 release. An LLM chops text into tokens and learns to predict the next one. TimesFM chops a time series into patches (contiguous windows of 32 time steps) and learns to predict the next patch. That is basically the whole idea. A decoder-only transformer, the same family as GPT, pointed at numbers instead of text. Patching matters for two practical reasons. Attention cost grows with sequence length, so grouping 32 points into one token keeps long histories affordable. And a patch captures a local shape (a weekly cycle, a spike, a slow drift) as a single unit, which is closer to how time series actually behave than treating each individual point as a token. The training data is the other half of the story. TimesFM was pretrained on a corpus of over a trillion time points spanning retail, finance, web traffic, energy, and synthetic data. It has seen enough patterns of "sales-shaped thing" and "traffic-shaped thing" that when you hand it yours, it recognizes the family. That is what makes zero-shot forecasting work. You also get uncertainty for free. The model outputs 9 quantiles (10th through 90th percentile) at every step, not just a single line. If you have ever had to bolt confidence intervals onto a forecast after the fact, this is a real convenience. Installation is a one-liner: pip install timesfm[torch] Or from source with uv: git clone https://github.com/google-research/timesfm.git cd timesfm uv venv && source .venv/bin/activate uv pip install -e .[torch] This is the API most tutorials and existing code use. You load a checkpoint, compile it once with a config, then call forecast(): import torch import numpy as np import timesfm torch.set_float32_matmul_precision("high") model = timesfm.TimesFM_2p5_200M_torch.from_pretrained( "google/timesfm-2.5-200m-pytorch" ) model.compile( timesfm.ForecastConfig( max_context=1024, max_horizon=256, normalize_inputs=True, use_continuous_quantile_head=True, force_flip_invariance=True, infer_is_positive=True, fix_quantile_crossing=True, ) ) point_forecast, quantile_forecast = model.forecast( horizon=12, inputs=[ np.linspace(0, 1, 100), np.sin(np.linspace(0, 20, 67)), ], ) point_forecast.shape # (2, 12) quantile_forecast.shape # (2, 12, 10) Two things worth noticing. The inputs are plain 1D arrays and they do not have to be the same length, which is genuinely nice when you are forecasting a batch of products with different histories. And a few config flags do real work: infer_is_positive stops the model predicting negative sales, fix_quantile_crossing prevents the 60th percentile landing below the 40th. Swapping in your own data is the boring part, which is the point: import pandas as pd df = pd.read_csv("weekly_demand.csv", parse_dates=["week"]) values = df["demand"].values.astype(np.float32) point, quantiles = model.forecast(horizon=52, inputs=[values]) That is a 52-week forecast with prediction intervals, from a CSV, with no training. TimesFM 3.0 landed in late August 2026, and it is a bigger jump than the version number suggests. Every checkpoint through 2.5 was strictly univariate. One series, its own history, nothing else. That is a real limitation, because most forecasting problems in the wild are not like that. If you are forecasting ice cream sales, past sales alone miss the picture: related product sales matter, foot traffic matters, and crucially, the promotion you already scheduled for next Tuesday matters. 3.0 is natively multivariate. It brings three things that were previously awkward or impossible: Multiple targets. Forecast several related series jointly and let the model use the correlations between them. Past covariates. Features you only know historically, like last month's foot traffic. Past-future covariates. Features you know in advance, like scheduled promotions, holidays, or a weather forecast. That last one is the interesting capability. The model learns the promotion-to-sales relationship from your historical context, then applies it to future days where you have a promotion planned. A univariate model just projects the weekly pattern forward and misses the bump entirely. Architecturally, 3.0 does this with alternating attention. Tokens attend horizontally across time (strictly causal, so no leakage from the future), then vertically across series at each time step, so the model can learn how a spike in one series relates to another. Those two layers alternate through the stack. It also stopped decoding autoregressively. Earlier versions generated one patch at a time, which meant latency and compounding errors over long horizons. 3.0 appends masked placeholder tokens for the whole future window and fills them all in a single forward pass. The 3.0 API is different from 2.5, so this is not a drop-in upgrade: import numpy as np from timesfm3 import TimesFM3Evaluator, ModelConfig config = ModelConfig( checkpoint_path="google/timesfm-3.0-pytorch", per_core_batch_size=16, device="cuda", ) forecaster = TimesFM3Evaluator(config) context_len, horizon = 128, 24 target = np.random.randn(3, context_len).astype(np.float32) past_only_cov = np.random.randn(1, context_len).astype(np.float32) past_future_cov = np.random.randn(2, context_len + horizon).astype(np.float32) outputs = list( forecaster.predict_batch( contexts=[target], horizon=horizon, past_only_covariates=[past_only_cov], past_future_covariates=[past_future_cov], return_quantiles=True, ) ) outputs[0].forecast.shape # (3, 24) outputs[0].quantiles.shape # (3, 24, 9) Note the shape of past_future_cov: it spans context plus horizon, because you are telling the model about events that have not happened yet. On benchmarks, Google reports 3.0 taking the top average rank among pretrained foundation models on GIFT-Eval, fev-bench, and the TIME leaderboard, on both point and probabilistic metrics, against competitors including Chronos-2 and the Toto 2.0 family. Notably, it wins even in univariate mode, before you give it any covariates at all. Read this part before you plan a sprint around it. The 3.0 weights are not open for commercial use. The source code in the repo is Apache-2.0, and model weights up to 2.5 are Apache-2.0. But the 3.0 pretrained weights ship under a separate timesfm-non-commercial-license-v1.0, restricted to non-commercial, non-production use. Commercial or production use of the default 3.0 weights is not permitted. So the practical situation right now is: TimesFM 2.5 TimesFM 3.0 Parameters 200M 330M Context length up to 16k patch-based, 32-step patches Multivariate No (XReg covariates bolted on) Yes, native Future-known covariates Limited Yes Decoding Autoregressive per patch Single forward pass Weights license Apache-2.0 Non-commercial only The best model is the one you probably cannot ship. The one you can ship is a version behind. That may change, and Google has said BigQuery integration for 3.0 is coming, but plan against what is true today. Yes, if any of these describe you: You have a lot of series and no time to model each one. This is the killer use case. Tuning ARIMA for one series is fine; doing it for 5,000 SKUs is not a job anyone wants. Zero-shot inference across a batch is a single call. You need a baseline yesterday. Even if you eventually build something bespoke, having a credible forecast in twenty minutes tells you whether the problem is hard and what score you need to beat. You want uncertainty without extra work. Quantiles come out of the box. You are already on Google Cloud. TimesFM is wired into BigQuery ML behind an AI.FORECAST SQL call, into Connected Sheets, and into Vertex Model Garden. If your data already lives in BigQuery, forecasting becomes a query rather than a project. Be skeptical if: You have one series and years of clean history. A well-tuned domain model with your actual business logic baked in will often beat a general-purpose one. Foundation models win on breadth, not on any single well-understood problem. Your data is genuinely weird. Sparse intermittent demand, hard structural breaks, series driven mostly by exogenous shocks the model cannot see. Zero-shot means the model brings priors from other people's data, and sometimes those priors are simply wrong for you. You need commercial deployment of the newest model. See the license section above. You need CPU-cheap inference at scale. It is a 200M to 330M parameter transformer. That is small next to an LLM but not free, and the examples assume a GPU. Repo and examples: github.com/google-research/timesfm One note: this is a research release, not an officially supported Google product. Treat it accordingly in anything load-bearing.