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 — предобученная базовая модель (foundation model) от Google Research для прогнозирования временных рядов. По духу она похожа на языковую модель, только работает с числовыми последовательностями.
Это библиотека или облачный сервис?Это библиотека на Python и предобученная модель, которую вы устанавливаете и запускаете сами. Google также предлагает её как продукт в BigQuery ML, Google Sheets и Vertex Model Garden, но этот репозиторий — версия с открытым исходным кодом.
Как установить и запустить её?Установка через PyPI (pip install timesfm) или клонирование репозитория, создание виртуального окружения и установка с поддержкой PyTorch.
Нужен ли PyTorch или есть другой бэкенд?Основной бэкенд — PyTorch, но есть также нативный бэкенд для MLX, который позволяет запускать TimesFM 3.0 на Apple Silicon без PyTorch, а также версия на Flax для более быстрого инференса.
Можно ли использовать предобученные веса TimesFM 3.0 в коммерческом продукте?Нет — предобученные веса 3.0 распространяются по отдельной некоммерческой лицензии, которая разрешает использование только в некоммерческих целях и не в продуктивной среде, хотя сам код распространяется по лицензии Apache-2.0.
Нужен ли Apple Silicon или она работает на любой машине?Работает на обычных компьютерах с Linux, macOS и Windows через PyTorch, а для Mac с чипами Apple Silicon есть дополнительный оптимизированный бэкенд MLX.
Чем TimesFM 3.0 отличается от предыдущих версий?TimesFM 3.0 добавляет встроенное многомерное прогнозирование с поддержкой ковариат как из прошлого, так и из прошлого и будущего, а также занимает первое место в основных бенчмарках, таких как fev-bench, TIME и GIFT-Eval.
Можно ли дообучить TimesFM на своих данных?Да, есть пример дообучения с использованием HuggingFace Transformers и PEFT (LoRA) в каталоге examples/finetuning.
Какой длины контекст и горизонт прогноза она поддерживает?TimesFM 2.5 поддерживает контекст длиной до 16k (против 2048 в версии 2.0) и непрерывное квантильное прогнозирование на горизонт до 1k с помощью необязательной квантильной головы.
Насколько быстр инференс на Apple Silicon?На Apple M4 Max с бэкендом MLX (модель на 330M, контекст 512, горизонт 64) достигается около 90 временных рядов в секунду при размере батча 1 и до 666 рядов в секунду при размере батча 32.
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, transformer, large-language-models, apple-silicon, inference
Creator
google-research
Size
4.5 MB
Stars
34.6K
Updated
CommitSep 29Releasev3.0.0Aug 28
Age
2y
Commits · 90 Days