google-research/timesfm

▲ 57 stars today★ 35,258⑂ 3,455

TimesFM (Time Series Foundation Model) is a pretrained time-series foundation model developed by Google Research for time-series forecasting.

About google-research/timesfm

google-research/timesfm is an open-source project on GitHub, mainly written in Python. TimesFM (Time Series Foundation Model) is a pretrained time-series foundation model developed by Google Research for time-series forecasting. It currently holds 35,258 stars and 3,455 forks with 275 open issues, and was last pushed on 2026-09-29 (repository created 2024-04-29).

Project Overview

Git Homed tracks it on the Today's Trending board, currently at rank #70 with 57 new stars today.

GitHub Repository Details

Repository google-research/timesfm · default branch master · size 4595 KB · watchers 224 · source: GitHub REST API and repository README

README

TimesFM

TimesFM (Time Series Foundation Model) is a pretrained time-series foundation model developed by Google Research for time-series forecasting.

A decoder-only foundation model for time-series forecasting, ICML 2024. google/timesfm-3.0-pytorch. Checkpoints up to 2.5: TimesFM Hugging Face Collection. Enterprise level SQL queries for scalability and reliability. For your daily spreadsheet. Dockerized endpoint for agentic calling.

This open version is not an officially supported Google product.

Latest Model Version: TimesFM 3.0 ✨

Archived Model Versions:

install timesfm==1.3.0` to install an older version of this package to load them.

--------------------------------------------------------------------------------

Update — September 2026

TimesFM 3.0 finishes rollout in Google Cloud BigQuery ML, supporting commercial and production uses (see clarified license notice).

Update — August 2026

TimesFM 3.0 is out!

TimesFM 3.0 introduces native multivariate time-series forecasting, flexible covariate support (both past-only and past-and-future covariates), superior zero-shot generalist capabilities, and top performance across all three major time-series foundation model benchmarks.

Key Highlights:

forecast multi-channel multivariate series as well as individual univariate series, with native support for past-only and past-and-future dynamic covariates without per-task tuning. forecasting tasks. 98 evaluation tasks.

License notice for pretrained weights

Important: The TimesFM source code in this repository is licensed under Apache-2.0, and model weights up to version 2.5 remain Apache-2.0. However, TimesFM 3.0 pretrained weights are distributed under the separate timesfm-non-commercial-license-v1.0 license and are restricted to non-commercial, non-production use. Commercial or production use of downloaded / self-hosted weights is not permitted.
Commercial & Production Use: Commercial and production use of TimesFM 3.0 is fully permitted through authorized Google Cloud services, including BigQuery ML, which are governed by the Google Cloud Terms of Service.

--------------------------------------------------------------------------------

Update - July 2, 2026

Updated PyPI to timesfm=2.0.2. See Install.

Update - Apr. 9, 2026

Added fine-tuning example using HuggingFace Transformers + PEFT (LoRA) — see timesfm-forecasting/examples/finetuning/. Also added unit tests (tests/) and incorporated several community fixes.

Shoutout to @kashif and @darkpowerxo.

Update - Mar. 19, 2026

Huge shoutout to @borealBytes for adding the support for AGENTS! TimesFM SKILL.md is out.

Update - Oct. 29, 2025

Added back the covariate support through XReg for TimesFM 2.5.

Update - Sept. 15, 2025

TimesFM 2.5 is out!

Comparing to TimesFM 2.0, this new 2.5 model:

quantile head. Since the Sept. 2025 launch, the following improvements have been completed for TimesFM 2.5:

1. ✅ Flax version of the model for faster inference. 2. ✅ Covariate support via XReg (see Oct. 2025 update). 3. ✅ Documentation, examples, and agent skill (see timesfm-forecasting/). 4. ✅ Fine-tuning example with LoRA via HuggingFace Transformers + PEFT (see timesfm-forecasting/examples/finetuning/). 5. ✅ Unit tests for core layers, configs, and utilities (see tests/).

Install

From PyPI

# Install TimesFM with PyTorch
pip install timesfm[torch]

Or, for MLX-native inference on Apple silicon (no PyTorch required)

pip install timesfm[mlx]

Local Install

1. Clone the repository:

    git clone https://github.com/google-research/timesfm.git
    cd timesfm
    

2. Create a virtual environment and install with PyTorch:

    # Using uv
    uv venv
    source .venv/bin/activate

# Install the package in editable mode with torch uv pip install -e .[torch]

--------------------------------------------------------------------------------

Code Examples: TimesFM 3.0

1. Univariate Forecasting (Variable Lengths)

Pass a batch of 1D NumPy arrays of different context lengths to forecast univariate time series:

import numpy as np
from timesfm3 import TimesFM3Evaluator, ModelConfig

Initialize TimesFM 3.0

config = ModelConfig( checkpoint_path="google/timesfm-3.0-pytorch", per_core_batch_size=32, device="cuda" ) forecaster = TimesFM3Evaluator(config)

Two univariate series of different lengths (100 and 72 steps)

ts1 = np.linspace(0, 1, 100).astype(np.float32) ts2 = np.sin(np.linspace(0, 24, 72)).astype(np.float32)

Generate forecast (point predictions + 9 quantiles: 0.1 to 0.9)

outputs = list(forecaster.predict_batch([ts1, ts2], horizon=12, return_quantiles=True, use_symmetric_averaging=False))

print("Series 1 forecast shape:", outputs[0].forecast.shape) # (12,) print("Series 1 quantiles shape:", outputs[0].quantiles.shape) # (12, 9)

print("Series 2 forecast shape:", outputs[1].forecast.shape) # (12,) print("Series 2 quantiles shape:", outputs[1].quantiles.shape) # (12, 9)

Apple Silicon: MLX backend

An MLX-native backend runs TimesFM 3.0 on Apple silicon without PyTorch. It mirrors the PyTorch TimesFM3Forecaster interface (predict / predict_batch, univariate or multivariate, with past-only and past-future covariates) and is numerically matched to it on google/timesfm-3.0-pytorch. Median forecast / quantile max abs error, context 512: 9.5e-7 / 1.8e-6 at horizon 64, 2.3e-6 / 2.7e-6 at horizon 128 (longer horizons stitch multiple output patches, so they are worth checking on their own).

import numpy as np
from timesfm3.mlx import TimesFM3Forecaster

forecaster = TimesFM3Forecaster.from_pretrained("google/timesfm-3.0-pytorch")

Univariate, long horizon (>= 128 spans several output patches).

context = np.sin(np.linspace(0, 40, 512)).astype(np.float32) out = forecaster.predict(context, horizon=128, return_quantiles=True) print(out.forecast.shape) # (128,) median forecast print(out.quantiles.shape) # (128, 9) 9 deciles

Batch many series through one forward pass.

outs = list(forecaster.predict_batch([context] * 32, horizon=128))

Multivariate targets and covariates work the same way as on the PyTorch backend (matched to 1.7e-6 on the checkpoint):

context_len, horizon = 256, 32

Two target variates: (num_variates, context_len).

target = np.stack([ np.sin(np.linspace(0, 24, context_len)), np.sin(np.linspace(1, 26, context_len)), ]).astype(np.float32)

past_only = np.random.randn(1, context_len).astype(np.float32) # (1, 256) past_future = np.sin( # (1, 256 + 32) np.linspace(0, 30, context_len + horizon) )[None, :].astype(np.float32)

out = forecaster.predict( target, horizon=horizon, past_only_covariates=past_only, past_future_covariates=past_future, return_quantiles=True, ) print(out.forecast.shape) # (2, 32) one forecast per target variate print(out.quantiles.shape) # (2, 32, 9)

Benchmarks (330M model, Apple M4 Max, context 512, horizon 64, fp32 with mx.compile):

| batch | p50 latency | throughput | |------:|------------:|-----------:| | 1 | 11.1 ms | 90 series/s | | 8 | 19.7 ms | 406 series/s | | 32 | 48.1 ms | 666 series/s |

Contexts longer than global_context (15,360) are truncated to their most recent points before decode, matching the PyTorch backend. use_symmetric_averaging, use_znorm, and padding_mode ("none" / "edge") are all supported and numerically matched to the PyTorch backend, so the MLX forecaster is a drop-in for the univariate and covariate forecasting paths.

2. Multivariate Forecasting with Covariates

Pass a 2D array of shape (num_variates, context_length) along with optional past-only and past-and-future covariates:

import numpy as np
from timesfm3 import TimesFM3Evaluator, ModelConfig

Initialize TimesFM 3.0

config = ModelConfig( checkpoint_path="google/timesfm-3.0-pytorch", per_core_batch_size=16, device="cuda" ) forecaster = TimesFM3Evaluator(config)

context_len = 128 horizon = 24

3 target variates across past context: (3, 128)

target = np.random.randn(3, context_len).astype(np.float32)

1 past-only covariate channel across past context: (1, 128)

past_only_cov = np.random.randn(1, context_len).astype(np.float32)

2 past-and-future covariate channels across context + horizon: (2, 152)

past_future_cov = np.random.randn(2, context_len + horizon).astype(np.float32)

Generate joint forecast across all 3 target variates

outputs = list( forecaster.predict_batch( contexts=[target], horizon=horizon, past_only_covariates=[past_only_cov], past_future_covariates=[past_future_cov], return_quantiles=True, use_symmetric_averaging=False, ) )

print("Multivariate forecast shape:", outputs[0].forecast.shape) # (3, 24) print("Multivariate quantiles shape:", outputs[0].quantiles.shape) # (3, 24, 9)

GitHub Stars & Activity

35,258Stars
3,455Forks
275Open issues
PythonLanguage

GitHub Popularity

GitHub stars35,258
Forks3,455
Open issues275
Primary languagePython
LicenseApache-2.0
Stars gained today57
Created2024-04-29
Last pushed2026-09-29

Trending History

Daily boardrank #70 · ▲ 57 stars

Related GitHub Projects

1

github / spec-kit

Python★ 148,048⑂ 13,291▲ 674 stars
→
2

harry0703 / MoneyPrinterTurbo

Python★ 140,036⑂ 22,331▲ 974 stars
→
3

D4Vinci / Scrapling

Python★ 98,536⑂ 10,315▲ 1,655 stars
→
4

microsoft / VibeVoice

Python★ 56,346⑂ 6,344▲ 223 stars
→
5

harvard-edge / cs249r_book

Python★ 29,988⑂ 3,716▲ 80 stars
→
6

google / skills

Python★ 22,596⑂ 1,902▲ 211 stars
→
7

Usagi-org / ai-goofish-monitor

Python★ 18,122⑂ 2,994▲ 240 stars
→
8

The-PR-Agent / pr-agent

Python★ 15,187⑂ 2,119▲ 442 stars
→

More Trending Repositories