timesfm README

The project's README from github.com/google-research/timesfm. As one markdown file: README.md.

TimesFM

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

This open version is not an officially supported Google product.

Latest Model Version: TimesFM 3.0

Archived Model Versions:

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:

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, for the time being, 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 the default pretrained weights is not permitted.

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:

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)

timesfm (google-research/timesfm)

Searching Database…

34.6K ·GitHub
Timesfm
这是什么？TimesFM 是谷歌研究院（Google Research）推出的预训练时间序列基础模型，用于时间序列预测。它的思路与语言模型相似，只是处理的对象是数值序列。
它是一个库还是托管服务？它是一个你可以自行安装和运行的 Python 库/预训练模型。谷歌还将它作为产品提供在 BigQuery ML、Google Sheets 和 Vertex Model Garden 中，但本仓库是其开源版本。
我该如何安装和运行？可以通过 PyPI 安装（pip install timesfm），也可以克隆仓库、创建虚拟环境，并安装带 PyTorch 支持的版本。
我需要 PyTorch，还是有其他后端可选？PyTorch 是主要后端。此外还提供原生 MLX 后端，可在 Apple Silicon 上不依赖 PyTorch 运行 TimesFM 3.0；另有 Flax 版本，推理速度更快。
我能否在商业产品中使用 TimesFM 3.0 的预训练权重？不能。3.0 预训练权重采用单独的非商业许可证，仅限非商业、非生产用途，尽管代码本身采用 Apache-2.0 许可证。
它是否必须使用 Apple Silicon，还是能在任何机器上运行？它可以通过 PyTorch 在常见的 Linux、macOS、Windows 机器上运行；另外还为 Apple Silicon Mac 提供了专门优化的 MLX 后端。
TimesFM 3.0 与早期版本有何不同？TimesFM 3.0 新增原生多变量预测，同时支持仅使用过去的协变量以及过去与未来协变量相结合的方式；在 fev-bench、TIME、GIFT-Eval 等主要基准测试中排名第一。
我能用自己的数据微调 TimesFM 吗？可以。examples/finetuning 目录中提供了一个微调示例，使用 HuggingFace Transformers 配合 PEFT（LoRA）。
TimesFM 支持多长的上下文和预测步长？TimesFM 2.5 支持最长 16k 的上下文长度（2.0 版本为 2048），并可通过可选的分位数头进行连续分位数预测，预测步长最长可达 1k。
在 Apple Silicon 上推理速度有多快？在 Apple M4 Max 上，使用 MLX 后端（330M 模型，上下文 512，预测步长 64）时，批大小为 1 时约每秒处理 90 条序列，批大小为 32 时最高可达每秒 666 条序列。
What are similar projects?timeseries-atlas, LTX-Video, petals, jeeves, Model-Optimizer, NeoHorse, Kronos, nanoGPT
Which topics is it in?forecasting, deep-neural-networks, time-series, foundation-models, pretrained-models, lora, google, fine-tuning, large-language-models, transformer, apple-silicon, inference
Creator
google-research
Size
4.5 MB
Stars
34.6K
Updated
CommitSep 29Releasev3.0.0Aug 28
Age
2y
Commits · 90 Days