timesfm Documentation

Technical Documentation: google-research/timesfm

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (`README.md`) Copy Section

TimesFM

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

• Paper:
  A decoder-only foundation model for time-series forecasting,
  ICML 2024.
• 🆕 TimesFM 3.0 Checkpoint:
  google/timesfm-3.0-pytorch. Checkpoints up to 2.5:
  TimesFM Hugging Face Collection.
• Google Reseach blog posts:
  • TimesFM-3: A zero-shot foundation model for multivariate forecasting
  • A decoder-only foundation model for time-series forecasting
• TimesFM in Google 1P Products:
  • BigQuery ML:
    Enterprise level SQL queries for scalability and reliability.
  • Google Sheets:
    For your daily spreadsheet.
  • Vertex Model Garden:
    Dockerized endpoint for agentic calling.

This open version is not an officially supported Google product.

Latest Model Version: TimesFM 3.0 ✨

Archived Model Versions:

• 2.5: relevant code under src/timesfm.
• 1.0 and 2.0: relevant code archived in the subdirectory v1. You can pip install timesfm==1.3.0 to install an older version of this package to load
  them.

Update — September 2026 Copy Chapter

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

Update — August 2026 Copy Chapter

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: Copy Section

• Native Multivariate & Univariate Forecasting with Covariates: Seamlessly
  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.
• Top Benchmark Performance:
  • 🥇 fev-bench: Rank #1 overall across 100 diverse real-world
    forecasting tasks.
  • 🥇 TIME Benchmark: Rank #1 overall across 50 domain datasets and
    98 evaluation tasks.
  • 🥇 GIFT-Eval: Rank #1 among all foundation models.

License notice for pretrained weights Copy Section

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 Copy Chapter

Updated PyPI to timesfm=2.0.2. See
Install.

Update - Apr. 9, 2026 Copy Chapter

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 Copy Chapter

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

Update - Oct. 29, 2025 Copy Chapter

Added back the covariate support through XReg for TimesFM 2.5.

Update - Sept. 15, 2025 Copy Chapter

TimesFM 2.5 is out!

Comparing to TimesFM 2.0, this new 2.5 model:

• uses 200M parameters, down from 500M.
• supports up to 16k context length, up from 2048.
• supports continuous quantile forecast up to 1k horizon via an optional 30M
  quantile head.
• gets rid of the frequency indicator.
• has a couple of new forecasting flags.

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 Copy Section

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:

   shell Copy

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

2. Create a virtual environment and install with PyTorch:

   shell Copy

   # 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 Copy Section

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):

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)

Overview (`v1/README.md`) Copy Section

TimesFM

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

• Paper: A decoder-only foundation model for time-series forecasting, to appear in ICML 2024.
• Google Research blog
• Hugging Face release

This repo contains the code to load public TimesFM checkpoints and run model
inference. Please visit our
Hugging Face release
to download model checkpoints.

This is not an officially supported Google product.

We recommend at least 32GB RAM to load TimesFM dependencies.

Need help? See TROUBLESHOOTING.md for common installation and usage issues.

Update - Dec. 30, 2024 Copy Chapter

• We are launching a 500m checkpoint as a part of TimesFM-2.0 release. This new checkpoint can be upto 25% better than v1.0 on leading benchmarks and also has a 4 times longer max. context length.
• Launched finetuning support that lets you finetune the weights of the pretrained TimesFM model on your own data.
• Launched ~zero-shot covariate support with external regressors. More details here.

Update - Feb. 17, 2024 Copy Chapter

• We are providing the option for finetuning using Pytorch, which mimics the previously added functionality from finetuning support.
• We are also providing the Multi-GPU finetuining with Pytorch. We currently support DDP multi-gpu finetuning, other variants of multi-gpu training (pipeline parallelism/model parallelism) might be added later. In order to use it, follow the steps in finetuning example .

Checkpoint timesfm-1.0-200m (-pytorch) Copy Chapter

timesfm-1.0-200m is our first open model checkpoint:

• It performs univariate time series forecasting for context lengths up to 512 timepoints and any horizon lengths, with an optional frequency indicator.
• It focuses on point forecasts, and does not support probabilistic forecasts. We experimentally offer quantile heads but they have not been calibrated after pretraining.

Checkpoint timesfm-2.0-500m (-jax/-pytorch) Copy Chapter

timesfm-2.0-500m is our second open model checkpoint:

• It performs univariate time series forecasting for context lengths up to 2048 timepoints and any horizon lengths, with an optional frequency indicator.
• It focuses on point forecasts. We experimentally offer 10 quantile heads but they have not been calibrated after pretraining.
• This new checkpoint can be upto 25% better than v1.0 on leading benchmarks and also has a 4 times longer max. context length.

Benchmarking Copy Chapter

TimesFM 2.0 has been added to GIFT-Eval which is one of the most comprehensive time-series bechmarks available. It takes the top spot in terms of aggregated MASE and CRPS, where it is 6% better than the next best model in terms of aggregated MASE.

Installation Copy Chapter

Local installation using poetry Copy Section

We will be using pyenv and poetry. In order to set these things up please follow the instructions here. Note that the PAX (or JAX) version needs to run on python 3.10.x and the PyTorch version can run on >=3.11.x. Therefore make sure you have two versions of python installed:

pyenv install 3.10
pyenv install 3.11
pyenv versions # to list the versions available (lets assume the versions are 3.10.15 and 3.11.10)

For PAX version installation do the following. Copy Section

pyenv local 3.10.15
poetry env use 3.10.15
poetry lock
poetry install -E  pax

After than you can run the timesfm under poetry shell or do poetry run python3 ....

For PyTorch version installation do the following. Copy Section

pyenv local 3.11.10
poetry env use 3.11.10
poetry lock
poetry install -E  torch

After than you can run the timesfm under poetry shell or do poetry run python3 ....

Additional Note:

If you plan to use the forecast_with_covariates function (which requires external regressors),
you need to install JAX and jaxlib. If you installed the base version of TimesFM (torch), you must manually install the dependencies for forecast_with_covariates support:

pip install jax jaxlib

Why is this needed?
The forecast_with_covariates method relies on the xreg_lib module, which depends on JAX and jaxlib. If these packages are not installed,
calling forecast_with_covariates will raise an error. However, due to a lazy import mechanism, xreg_lib (and hence JAX/jaxlib) is not needed for standard forecast calls.

Notes Copy Section

1. Running the provided benchmarks would require additional dependencies. Please see the experiments folder.

2. The dependency lingvo does not support ARM architectures, and the code is not working for machines with Apple silicon. We are aware of this issue and are working on a solution. Stay tuned.

Install from PyPI (and publish) Copy Section

On python 3.11 you can install the torch version using:

pip install timesfm[torch]

On python 3.10 you can install the pax version using:

pip install timesfm[pax]

Usage Copy Chapter

Initialize the model and load a checkpoint. Copy Section

Then the base class can be loaded as,

import timesfm

# Loading the timesfm-2.0 checkpoint:
# For PAX
tfm = timesfm.TimesFm(
      hparams=timesfm.TimesFmHparams(
          backend="gpu",
          per_core_batch_size=32,
          horizon_len=128,
          num_layers=50,
          context_len=2048,

          use_positional_embedding=False,
      ),
      checkpoint=timesfm.TimesFmCheckpoint(
          huggingface_repo_id="google/timesfm-2.0-500m-jax"),
  )

# For Torch
tfm = timesfm.TimesFm(
      hparams=timesfm.TimesFmHparams(
          backend="gpu",
          per_core_batch_size=32,
          horizon_len=128,
          num_layers=50,
          use_positional_embedding=False,
          context_len=2048,
      ),
      checkpoint=timesfm.TimesFmCheckpoint(
          huggingface_repo_id="google/timesfm-2.0-500m-pytorch"),
  )

# Loading the timesfm-1.0 checkpoint:
# For PAX
tfm = timesfm.TimesFm(
      hparams=timesfm.TimesFmHparams(
          backend="gpu",
          per_core_batch_size=32,
          horizon_len=128,
      ),
      checkpoint=timesfm.TimesFmCheckpoint(
          huggingface_repo_id="google/timesfm-1.0-200m"),
  )

# For Torch
tfm = timesfm.TimesFm(
      hparams=timesfm.TimesFmHparams(
          backend="gpu",
          per_core_batch_size=32,
          horizon_len=128,
      ),
      checkpoint=timesfm.TimesFmCheckpoint(
          huggingface_repo_id="google/timesfm-1.0-200m-pytorch"),
  )

Note some of the parameters are fixed to load the 200m and 500m models

1. The context_len in hparams here can be set as the max context length of the model (a maximum of 2048 for 2.0 models and 512 for 1.0 models). It needs to be a multiplier of input_patch_len, i.e. a multiplier of 32. You can provide a shorter series to the tfm.forecast() function and the model will handle it. The input time series can have any context length. Padding / truncation will be handled by the inference code if needed.

2. The horizon length can be set to anything. We recommend setting it to the largest horizon length you would need in the forecasting tasks for your application. We generally recommend horizon length <= context length but it is not a requirement in the function call.

3. backend is one of "cpu", "gpu", case sensitive.

Perform inference Copy Section

We provide APIs to forecast from either array inputs or pandas dataframe. Both forecast methods expect (1) the input time series contexts, (2) along with their frequencies. Please look at the documentation of the functions tfm.forecast() and tfm.forecast_on_df() for detailed instructions.

In particular regarding the frequency, TimesFM expects a categorical indicator valued in {0, 1, 2}:

• 0 (default): high frequency, long horizon time series. We recommend using this for time series up to daily granularity.
• 1: medium frequency time series. We recommend using this for weekly and monthly data.
• 2: low frequency, short horizon time series. We recommend using this for anything beyond monthly, e.g. quarterly or yearly.

This categorical value should be directly provided with the array inputs. For dataframe inputs, we convert the conventional letter coding of frequencies to our expected categories, that

• 0: T, MIN, H, D, B, U
• 1: W, M
• 2: Q, Y

Notice you do NOT have to strictly follow our recommendation here. Although this is our setup during model training and we expect it to offer the best forecast result, you can also view the frequency input as a free parameter and modify it per your specific use case.

Examples:

Array inputs, with the frequencies set to low, medium and high respectively.

import numpy as np
forecast_input = [
    np.sin(np.linspace(0, 20, 100)),
    np.sin(np.linspace(0, 20, 200)),
    np.sin(np.linspace(0, 20, 400)),
]
frequency_input = [0, 1, 2]

point_forecast, experimental_quantile_forecast = tfm.forecast(
    forecast_input,
    freq=frequency_input,
)

pandas dataframe, with the frequency set to "M" monthly.

import pandas as pd

# e.g. input_df is
#       unique_id  ds          y
# 0     T1         1975-12-31  697458.0
# 1     T1         1976-01-31  1187650.0
# 2     T1         1976-02-29  1069690.0
# 3     T1         1976-03-31  1078430.0
# 4     T1         1976-04-30  1059910.0
# ...   ...        ...         ...
# 8175  T99        1986-01-31  602.0
# 8176  T99        1986-02-28  684.0
# 8177  T99        1986-03-31  818.0
# 8178  T99        1986-04-30  836.0
# 8179  T99        1986-05-31  878.0

forecast_df = tfm.forecast_on_df(
    inputs=input_df,
    freq="M",  # monthly
    value_name="y",
    num_jobs=-1,
)

Covariates Support Copy Chapter

We now have an external regressors library on top of TimesFM that can support static covariates as well as dynamic covariates available in the future. We have an usage example in notebooks/covariates.ipynb.

If you plan to use the forecast_with_covariates on timesfm torch version, you need to install JAX and jaxlib.
You must manually install the dependencies for forecast_with_covariates support:

pip install jax jaxlib

Let's take a toy example of forecasting sales for a grocery store:

Task: Given the observed the daily sales of this week (7 days), forecast the daily sales of next week (7 days).

Product: ice cream
Daily_sales: [30, 30, 4, 5, 7, 8, 10]
Category: food
Base_price: 1.99
Weekday: [0, 1, 2, 3, 4, 5, 6, 0, 1, 2, 3, 4, 5, 6]
Has_promotion: [Yes, Yes, No, No, No, Yes, Yes, No, No, No, No, No, No, No]
Daily_temperature: [31.0, 24.3, 19.4, 26.2, 24.6, 30.0, 31.1, 32.4, 30.9, 26.0, 25.0, 27.8, 29.5, 31.2]

Product: sunscreen
Daily_sales: [5, 7, 12, 13, 5, 6, 10]
Category: skin product
Base_price: 29.99
Weekday: [0, 1, 2, 3, 4, 5, 6, 0, 1, 2, 3, 4, 5, 6]
Has_promotion: [No, No, Yes, Yes, No, No, No, Yes, Yes, Yes, Yes, Yes, Yes, Yes]
Daily_temperature: [31.0, 24.3, 19.4, 26.2, 24.6, 30.0, 31.1, 32.4, 30.9, 26.0, 25.0, 27.8, 29.5, 31.2]

In this example, besides the Daily_sales, we also have covariates Category, Base_price, Weekday, Has_promotion, Daily_temperature. Let's introduce some concepts:

Static covariates are covariates for each time series.

• In our example, Category is a static categorical covariate,
• Base_price is a static numerical covariates.

Dynamic covariates are covaraites for each time stamps.

• Date / time related features can be usually treated as dynamic covariates.
• In our example, Weekday and Has_promotion are dynamic categorical covariates.
• Daily_temperate is a dynamic numerical covariate.

Notice: Here we make it mandatory that the dynamic covariates need to cover both the forecasting context and horizon. For example, all dynamic covariates in the example have 14 values: the first 7 correspond to the observed 7 days, and the last 7 correspond to the next 7 days.

We can now provide the past data of the two products along with static and dynamic covariates as a batch input to TimesFM and produce forecasts that take into the account the covariates. To learn more, check out the example in notebooks/covariates.ipynb.

Finetuning Copy Chapter

We have provided an example of finetuning the model on a new dataset in notebooks/finetuning.ipynb.

Contribution Style guide Copy Chapter

If you would like to submit a PR please make sure that you use our formatting style. We use yapf for formatting with the following options,

[style]
based_on_style = google
# Add your custom style rules here
indent_width = 2
spaces_before_comment = 2

Please run yapf --in-place --recursive <filename> on all affected files.

Overview (`timesfm3-usage/benchmarks/README.md`) Copy Section

TimesFM 3.0 Benchmarks

Evaluation notebooks, runners, and results for TimesFM 3.0:

• fev_bench/: AutoGluon FEV-Bench (100 tasks)
• time_bench/: ICML TIME Benchmark (98 tasks)
• gift_eval/: Salesforce GIFT-Eval

Overview (`v1/peft/README.md`) Copy Section

Fine-Tuning Pipeline

This folder contains a generic fine-tuning pipeline designed to support multiple PEFT fine-tuning strategies.

Features Copy Chapter

• Supported Fine-Tuning Strategies:
  • Full Fine-Tuning: Adjusts all parameters of the model during training.
  • Linear Probing: Fine-tunes only the residual blocks and the embedding layer, leaving other parameters unchanged.
  • LoRA (Low-Rank Adaptation): A memory-efficient method that fine-tunes a small number of parameters by decomposing the weight matrices into low-rank matrices.
  • DoRA (Directional LoRA): An extension of LoRA that decomposes pre-trained weights into magnitude and direction components. It uses LoRA for directional adaptation, enhancing learning capacity and stability without additional inference overhead.

Usage Copy Chapter

Fine-Tuning Script Copy Section

The provided finetune.py script allows you to fine-tune a model with specific configurations. You can customize various parameters to suit your dataset and desired fine-tuning strategy.

Example Usage:

source finetune.sh

This script runs the finetune.py file with a predefined set of hyperparameters for the model. You can adjust the parameters in the script as needed.

Available Options Copy Section

Run the script with the --help flag to see a full list of available options and their descriptions:

python3 finetune.py --help

Script Configuration
You can modify the following key parameters directly in the finetune.sh script:
Fine-Tuning Strategy: Toggle between full fine-tuning, LoRA [--use-lora], DoRA [[--use-dora]], or Linear Probing [--use-linear-probing].

Performance Comparison Copy Section

The figure below compares the performance of LoRA/DoRA against Linear Probing under the following conditions:

• Training data split: 60% train, 20% validation, 20% test.
• Benchmark: context_len=128, horizon_len=96
• Fine-tuning: context_len=128, horizon_len=128
• Black: Best result.
• Blue: Second best result.

Overview (`timesfm-forecasting/examples/finetuning/README.md`) Copy Section

Fine-Tuning TimesFM 2.5 with LoRA

Parameter-efficient fine-tuning of
TimesFM 2.5
using HuggingFace Transformers and PEFT (LoRA).

This approach is based on the fine-tuning workflow by
@kashif at HuggingFace
(notebook).

How It Works Copy Chapter

TimesFM 2.5 is available as a standard
Transformers model
(TimesFm2_5ModelForPrediction). This means it supports the full Transformers
ecosystem out of the box, including:

• PEFT adapters — LoRA, QLoRA, etc. via the
  peft library
• All attention backends — eager, SDPA, Flash Attention 2/3, Flex Attention
• Standard from_pretrained / save_pretrained workflow

The model's forward pass natively computes a training loss when future_values
are provided, so fine-tuning requires nothing more than a standard PyTorch
training loop.

Quick Start Copy Chapter

Install Copy Section

pip install transformers accelerate peft pandas pyarrow scikit-learn

Train Copy Section

# Fine-tune with default settings on the retail sales dataset
python finetune_lora.py

# Custom hyperparameters
python finetune_lora.py \
    --epochs 20 \
    --batch_size 64 \
    --lr 5e-5 \
    --lora_r 8 \
    --lora_alpha 16 \
    --context_len 64 \
    --horizon_len 13 \
    --output_dir my-retail-adapter

Evaluate Copy Section

# Evaluate a previously trained adapter (skip training)
python finetune_lora.py --eval_only --output_dir timesfm2_5-retail-lora

Key Concepts Copy Chapter

No External Normalisation Copy Section

TimesFM 2.5 applies its own internal instance normalisation (RevIN). Do not
normalise your data externally — feed raw values and let the model handle it.

Random Window Sampling Copy Section

Following Chronos-2,
each training example is a random (context, horizon) window sliced from one of
the input series. This is more data-efficient than always using the same
fixed window per series.

LoRA Target Modules Copy Section

Using target_modules="all-linear" applies LoRA to every linear layer in the
model. With r=4 this adds only ~0.6% trainable parameters (~1.4M out of
~232M), which is enough to meaningfully adapt the model to a new domain.

CLI Options Copy Chapter

Acknowledgements Copy Chapter

The Transformers integration and fine-tuning approach were developed by
@kashif at HuggingFace. See the original notebook:
https://github.com/huggingface/notebooks/blob/main/examples/timesfm2_5.ipynb

Overview (`timesfm-forecasting/examples/global-temperature/README.md`) Copy Section

TimesFM Forecast Report: Global Temperature Anomaly (2025)

Model: TimesFM 1.0 (200M) PyTorch
Generated: 2026-02-21
Source: NOAA GISTEMP Global Land-Ocean Temperature Index

Executive Summary Copy Chapter

TimesFM forecasts a mean temperature anomaly of 1.19°C for 2025, slightly below the 2024 average of 1.25°C. The model predicts continued elevated temperatures with a peak of 1.30°C in March 2025 and a minimum of 1.06°C in December 2025.

Input Data Copy Chapter

Historical Temperature Anomalies (2022-2024) Copy Section

Statistics:

• Total observations: 36 months
• Mean anomaly: 1.09°C
• Trend (2022→2024): +0.37°C

Raw Forecast Output Copy Chapter

Point Forecast and Confidence Intervals Copy Section

JSON Output Copy Section

{
  "model": "TimesFM 1.0 (200M) PyTorch",
  "input": {
    "source": "NOAA GISTEMP Global Temperature Anomaly",
    "n_observations": 36,
    "date_range": "2022-01 to 2024-12",
    "mean_anomaly_c": 1.089
  },
  "forecast": {
    "horizon": 12,
    "dates": ["2025-01", "2025-02", "2025-03", "2025-04", "2025-05", "2025-06",
              "2025-07", "2025-08", "2025-09", "2025-10", "2025-11", "2025-12"],
    "point": [1.259, 1.286, 1.295, 1.221, 1.170, 1.146, 1.170, 1.203, 1.191, 1.149, 1.080, 1.061]
  },
  "summary": {
    "forecast_mean_c": 1.186,
    "forecast_max_c": 1.295,
    "forecast_min_c": 1.061,
    "vs_last_year_mean": -0.067
  }
}

Visualization Copy Chapter

Findings Copy Chapter

Key Observations Copy Section

1. Slight cooling trend expected: The model forecasts a mean anomaly 0.07°C below 2024 levels, suggesting a potential stabilization after the record-breaking temperatures of 2023-2024.

2. Seasonal pattern preserved: The forecast shows the expected seasonal variation with higher anomalies in late winter (Feb-Mar) and lower in late fall (Nov-Dec).

3. Widening uncertainty: The 90% CI expands from ±0.04°C in January to ±0.08°C in December, reflecting typical forecast uncertainty growth over time.

4. Peak temperature: March 2025 is predicted to have the highest anomaly at 1.30°C, potentially approaching the September 2023 record of 1.47°C.

Limitations Copy Section

• TimesFM is a zero-shot forecaster without physical climate model constraints
• The 36-month training window may not capture multi-decadal climate trends
• El Niño/La Niña cycles are not explicitly modeled

Recommendations Copy Section

• Use this forecast as a baseline comparison for physics-based climate models
• Update forecast quarterly as new observations become available
• Consider ensemble approaches combining TimesFM with other methods

Reproducibility Copy Chapter

Files Copy Section

How to Reproduce Copy Section

# Install dependencies
uv pip install "timesfm[torch]" matplotlib pandas numpy

# Run the complete example
cd scientific-skills/timesfm-forecasting/examples/global-temperature
./run_example.sh

Technical Notes Copy Chapter

API Discovery Copy Section

The TimesFM PyTorch API differs from the GitHub README documentation:

Documented (GitHub README):

model = timesfm.TimesFm(
    context_len=512,
    horizon_len=128,
    backend="gpu",
)
model.load_from_google_repo("google/timesfm-2.5-200m-pytorch")

Actual Working API:

hparams = timesfm.TimesFmHparams(horizon_len=12)
checkpoint = timesfm.TimesFmCheckpoint(
    huggingface_repo_id="google/timesfm-1.0-200m-pytorch"
)
model = timesfm.TimesFm(hparams=hparams, checkpoint=checkpoint)

TimesFM 2.5 PyTorch Issue Copy Section

The google/timesfm-2.5-200m-pytorch checkpoint downloads as model.safetensors, but the TimesFM loader expects torch_model.ckpt. This causes a FileNotFoundError at model load time. Using TimesFM 1.0 PyTorch resolves this issue.

Report generated by TimesFM Forecasting Skill (claude-scientific-skills)

Overview (`timesfm3-usage/benchmarks/fev_bench/README.md`) Copy Section

AutoGluon FEV-Bench

Evaluates TimesFM 3.0 on AutoGluon's 100-task FEV benchmark suite.

Usage Copy Chapter

pip install -e . autogluon.timeseries
python run_fev_bench.py

Overview (`timesfm3-usage/benchmarks/gift_eval/README.md`) Copy Section

Salesforce GIFT-Eval

Evaluates TimesFM 3.0 on the GIFT-Eval benchmark suite.

Usage Copy Chapter

pip install -e . datasets gluonts
python evaluate_all_gift.py

Overview (`timesfm3-usage/benchmarks/time_bench/README.md`) Copy Section

ICML TIME Benchmark

Evaluates TimesFM 3.0 on the ICML TIME benchmark (98 tasks).

Usage Copy Chapter

pip install -e . datasets gluonts
python run_time_bench.py

Overview (`v1/experiments/extended_benchmarks/README.md`) Copy Section

Extended Benchmarks

The benchmark setting has been borrowed from Nixtla's original benchmarking of time-series foundation models against a strong statistical ensemble. Later more datasets were added by the Chronos team in this pull request. We compare on all the datasets in this extended benchmarks.

Running TimesFM on the benchmark Copy Chapter

We need to add the following packages for running these benchmarks. Follow the installation instructions till before poetry lock. Then,

poetry add git+https://github.com/awslabs/gluon-ts.git
poetry lock
poetry install --only <pax or pytorch>

To run the timesfm on the benchmark do:

poetry run python3 -m experiments.extended_benchmarks.run_timesfm --model_path=google/timesfm-1.0-200m(-pytorch) --backend="gpu"

Note: In the current version of TimesFM we focus on point forecasts and therefore the mase, smape have been calculated using the quantile head corresponding to the median i.e 0.5 quantile. We do offer 10 quantile heads but they have not been calibrated after pretraining. We recommend using them with caution or calibrate/conformalize them on a hold out for your applications. More to follow on later versions.

Benchmark Results for TimesFM-1.0 Copy Chapter

Update: We have added TimeGPT-1 to the benchmark results. We had to remove the Dominick dataset as we were not able to run TimeGPT-1 on this benchmark. Note that the previous results including Dominick remain available at ./tfm_results.png. In order to reproduce the results for TimeGPT-1, please run run_timegpt.py.

Remark: All baselines except the ones involving TimeGPT were run performed on a g2-standard-32. Since TimeGPT-1 can only be accessed by an API, the time column might not reflect the true speed of the model as it also includes the communication cost. Moreover, we are not sure about the exact backend hardware for TimeGPT. The TimesFM latency numbers are from the PAX version.

We can see that TimesFM performs the best in terms of both mase and smape. More importantly it is much faster than the other methods, in particular it is more than 600x faster than StatisticalEnsemble and 80x faster than Chronos (Large).

Note: This benchmark only compares on one small horizon window for long horizon datasets like ETT hourly and 15 minutes. More in depth comparison on longer horizon rolling validation tasks are presented in our long horizon benchmarks.

Overview (`v1/experiments/long_horizon_benchmarks/README.md`) Copy Section

Extended Benchmarks

We benchmark on the original test set for ETT datasets as per long horizon benchmark papers (see here for example.) In the original benchmark, rolling validation task on all test windows (with a stride of 1) is considered. While we can easily run our method on this task, the baselines can take a very long time to run. Therefore we present results on a modified task with stride between windows set to Horizon length i.e all disjoint horizons in the test period is considered.

All experiments were performed on a g2-standard-32. We compare TimesFM with Amazon-Chronos.

Running TimesFM on the benchmark Copy Chapter

We need to add the following packages for running these benchmarks. Follow the installation instructions till before poetry lock. Then,

poetry add git+https://github.com/awslabs/gluon-ts.git
poetry add git+https://github.com/amazon-science/chronos-forecasting.git
poetry lock
poetry install --only pax

Note that for now only the pax version runs on this benchmark, because we had to remove the old tf dependency from the pytorch version. We will fix this issue soon.

To run the timesfm on the benchmark do:

poetry run python3 -m experiments.long_horizon_benchmarks.run_eval \
--model_path=google/timesfm-1.0-200m --backend="gpu" \
--pred_len=96 --context_len=512 --dataset=etth1

In the above, <model_path> should point to the checkpoint directory that can be downloaded from HuggingFace.

For running chronos on the same benchmark you can run the command,

poetry run python3 -m experiments.long_horizon_benchmarks.run_eval \
--model_path=amazon/chronos-t5-mini --backend="gpu" \
--pred_len=96 --context_len=512 --dataset=etth1

You can change the model size from "mini" to "large" as required. The datasets we benchmark on are etth1, etth2, ettm1 and ettm2.

Benchmark Results for TimesFM-1.0 Copy Chapter

We compare the performance on horizon lengths of 96, 192 and 336, while context length is held fixed at 512.

We can see that TimesFM performs the best in terms of both wape and smape. More importantly it is much faster than the other methods, in particular it is more than 1000x faster than Chronos (Large).

V1 Docs Contributing (`v1/docs/contributing.md`) Copy Section

How to Contribute

We would love to accept your patches and contributions to this project.

Before you begin Copy Chapter

Sign our Contributor License Agreement Copy Section

Contributions to this project must be accompanied by a
Contributor License Agreement (CLA).
You (or your employer) retain the copyright to your contribution; this simply
gives us permission to use and redistribute your contributions as part of the
project.

If you or your current employer have already signed the Google CLA (even if it
was for a different project), you probably don't need to do it again.

Visit https://cla.developers.google.com/ to see your current agreements or to
sign a new one.

Review our Community Guidelines Copy Section

This project follows Google's Open Source Community
Guidelines.

Contribution process Copy Chapter

Code Reviews Copy Section

All submissions, including submissions by project members, require review. We
use GitHub pull requests
for this purpose.

--- METRICS ---

• Files Extracted: 12
• Estimated Token Budget: ~11061 tokens
• Canonical Reference: https://codewiki.google/github.com/google-research/timesfm