Read the whole setupGet the setup that works.
Drop your email and unlock the rest: what you need, the install for your platform, which model version to pick for commercial use, and the first real forecast.
One email. No follow-up unless I ship something that fits.
WHAT YOU NEED- Python 3.10 or newer
- PyTorch, or MLX if you are on Apple Silicon and want to skip it
- A time series with a timestamp, even a rough one, to forecast against
INSTALLPyPI for most people, MLX for Mac
The PyPI install is the fast path. Pick the 2.5 weights explicitly if commercial use matters, since the library defaults to the newest checkpoint otherwise.
The install
terminalPyTorch path
$ pip install timesfm[torch] → or: pip install timesfm[mlx] # Apple Silicon, no PyTorch
The local install path (git clone plus uv pip install -e .[torch]) is worth it only if you plan to read or modify the model code, not for normal use.
Prove itForecast a short synthetic series, a straight ramp or a simple sine wave, first. A projection that continues the visible pattern confirms the model loaded and ran correctly before you point it at real data.
CONFIGUREThe one setting that is actually a licence decision
Which checkpoint you load is not a performance tuning knob, it is the difference between a model you can ship and one you cannot.
model configcommercial-safe choice
# NOT for production/commercial use: checkpoint_path = "google/timesfm-3.0-pytorch" # Apache-2.0, safe for commercial use: checkpoint_path = "google/timesfm-2.5"
| Setting | Default | Why I change it |
|---|
| checkpoint_path | TimesFM 3.0 | Non-commercial license. Pin to a 2.5 checkpoint for anything shipping in a paid product. |
| context length | up to 16k on 2.5 | Longer context costs more compute per forecast. Match it to how much real history you actually have, not the maximum. |
CovariatesTimesFM 3.0 adds native multivariate forecasting with past-and-future covariates, useful for a metric with a known future input like planned ad spend. 2.5 supports covariates too, through XReg, with a slightly different API.
DAILY DRIVINGFeed it a series, get a horizon back
The workflow is the same whether you are forecasting signups, revenue, or support ticket volume. The only real variable is how far out you ask it to project.
- Feed raw history. A plain array of numbers with a consistent time step is enough, no manual seasonality decomposition required first.
- Ask for a specific horizon. A week, a month, a quarter, set explicitly rather than accepted at a default that may not match your planning cycle.
- Treat it as one input, not the answer. A forecast informs a plan, it does not replace the judgment call about what to actually do with it.
Google's own use inside BigQuery ML and Connected Sheets is the same model, wrapped for people who would rather write SQL or use a spreadsheet than Python.
WHEN IT DRIFTSTwo failures, both configuration
Forecast looks flat or wrong
Context length is too short for the series' real seasonality. Feed more history, up to the 16k limit on 2.5, before assuming the model is wrong.
Legal flags the model in review
The default checkpoint is 3.0, which is non-commercial only. Point checkpoint_path at a 2.5 weight instead before it ships.
ResetThere is no local state to corrupt. Reinstalling the package and re-downloading the checkpoint from Hugging Face resolves nearly everything.
THE SHAPE OF ITWhere everything lives
src/timesfm/the 2.5 and earlier model code timesfm3-usage/TimesFM 3.0 usage examples and the evaluator API timesfm-forecasting/examples/finetuning/the optional LoRA fine-tuning example v1/archived 1.0 and 2.0 code, installable via `timesfm==1.3.0` tests/unit tests for the core layers and configs
Model weights download from Hugging Face on first use and cache locally. Nothing here needs a Google Cloud account unless you specifically want the BigQuery ML or Vertex integrations.
That is the whole setupOne pip install, one checkpoint choice that is really a licence choice, and a spreadsheet average stops being your forecasting method. Pick 2.5 the moment commercial use is on the table.
Open on GitHub →
↑ Unlocks the moment you submit the form above.
