# timesfm

> Pretrained Google model that forecasts time series without training on your data

- Repository: https://github.com/google-research/timesfm
- Category: Models & local AI
- Stars: 34,718 · Forks: 3,358 · Language: Python · License: Apache-2.0
- Experience: Some experience
- Page: https://ir.adyog.com/repos/google-research/timesfm/

Forecasting usually means training a model for each dataset. TimesFM is already trained on a large body of time series, so you hand it your history and ask for the next steps. It is a decoder-only model, described in an ICML 2024 paper.

You pass in arrays of past values and get back a point forecast plus nine quantiles (0.1 to 0.9) for the horizon you choose. Version 3.0 forecasts several variates at once and accepts covariates, which are extra signals known only for the past, or for the future too. There are PyTorch and Apple-silicon MLX backends.

The README says 3.0 ranks first on three forecasting benchmarks (fev-bench, TIME, GIFT-Eval), which is the authors' own claim. Licensing matters: the code is Apache-2.0 and weights up to 2.5 are too, but 3.0 weights are for non-commercial, non-production use only. Commercial use goes through Google Cloud services such as BigQuery ML.

## What it does

- **Zero-shot forecasting**: Forecasts from a pretrained checkpoint with no per-task tuning. Series of different lengths can go in one batch.
- **Multivariate and covariates**: Version 3.0 forecasts several variates jointly and supports past-only and past-and-future covariates.
- **Quantile output**: Each forecast can come with nine quantiles, so you get an uncertainty range and not just a single line.
- **PyTorch and MLX backends**: Install with PyTorch, or use the MLX backend on Apple silicon without PyTorch. The README reports the two match numerically.
- **Older versions and fine-tuning**: Versions 1.0 to 2.5 remain available. A LoRA fine-tuning example using Hugging Face Transformers and PEFT is included, along with an agent skill file.

## What you could build

- Forecast demand, traffic or sensor readings from past values without training a model.
- Predict several related series together, using known future inputs such as promotions or holidays as covariates.
- Produce forecast ranges with quantiles to show uncertainty on a dashboard.
- Run fast batch forecasting on a Mac using the MLX backend.
- Fine-tune the 2.5 model on your own data with the LoRA example.

## Who it's for

Suits data scientists and students who already work with Python and NumPy and know basic forecasting ideas like horizon and covariates; check the license first if the work is commercial.

## Get started

Install the package with the PyTorch extra, or the MLX extra on Apple silicon. Then load the google/timesfm-3.0-pytorch checkpoint and pass in NumPy arrays of past values, as in the README examples.

```
pip install timesfm[torch]
```
```
pip install timesfm[mlx]
```

Tags: time-series, forecasting, foundation-model, google-research, pytorch