TimesFM-3 Studio

A local web studio for Google's TimesFM-3 forecasting model. It does four things, all without training a model and without your data leaving your machine:

• Forecast several related series together, including drivers you know in advance (promotions, holidays, weather forecasts).

• Backtest by hiding recent history, forecasting it, and scoring the result against a simple baseline.

• What-if: change the future drivers and compare the result with the baseline forecast.

• Anomalies: flag historical points far outside what the model expected.

It ships with six real public datasets (NOAA CO₂, Capital Bikeshare, ETTh1, NYC taxi, sunspots, Wikipedia pageviews) and five synthetic demos. An MCP server exposes the same tools to AI agents. See webapp/README.md for how the studio works and MCP-SERVER.md for the agent tools.

License: the code is Apache-2.0. The TimesFM-3 model weights are not included. You download them from Hugging Face, and they are licensed for non-commercial, non-production use only.

Requirements

You don't need to install Python yourself. uv installs Python 3.12 into the project folder.

Related MCP server: timesfm-mcp

Install on macOS

Open Terminal and run:

# 1. Install uv (skip if you already have it)
curl -LsSf https://astral.sh/uv/install.sh | sh
# Close and reopen Terminal so the `uv` command is found.

# 2. Get the code
git clone https://github.com/TheAIHorizon/timesfm3-studio.git
cd timesfm3-studio

# 3. Create the environment and install the studio
uv venv --python 3.12 .venv
uv pip install --python .venv/bin/python -e ".[torch,web]"

Start the studio: double-click start_studio.command in Finder, or run ./start_studio.command. The first time, it offers to download the model weights (about 1.3 GB from Google's Hugging Face page, no account needed). It shows the non-commercial licence first and waits for you to type y. Once the weights are there, your browser opens at http://127.0.0.1:7863. Press Ctrl+C in the Terminal window to stop it.

To download the weights without starting the studio, run .venv/bin/python download_model.py.

If macOS says the file can't be opened, right-click it, choose Open, then Open again. You only need to do this once.

Install on Windows

Open PowerShell and run:

# 1. Install uv (skip if you already have it)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
# Close and reopen PowerShell so the `uv` command is found.

# 2. Get the code (needs Git: https://git-scm.com/download/win)
#    Or download the ZIP from GitHub (Code > Download ZIP), unzip it, and cd into the folder.
git clone https://github.com/TheAIHorizon/timesfm3-studio.git
cd timesfm3-studio

# 3. Create the environment and install the studio
uv venv --python 3.12 .venv
uv pip install --python .venv\Scripts\python.exe -e ".[torch,web]"

# 4. Optional, for NVIDIA GPUs only: replace the CPU build of PyTorch with a CUDA build.
#    Get the exact command from https://pytorch.org/get-started/locally/
#    (choose Windows, Pip, Python and your CUDA version). It looks like this:
#    uv pip install --python .venv\Scripts\python.exe torch --index-url https://download.pytorch.org/whl/cu128 --reinstall

Start the studio: double-click start_studio.bat in File Explorer, or run .\start_studio.bat. The first time, it offers to download the model weights (about 1.3 GB from Google's Hugging Face page, no account needed). It shows the non-commercial licence first and waits for you to type y. Once the weights are there, your browser opens at http://127.0.0.1:7863. Press Ctrl+C in the window to stop it.

To download the weights without starting the studio, run .venv\Scripts\python.exe download_model.py.

If Windows SmartScreen warns about the file, click More info, then Run anyway.

After installing

• The status dot in the top-right corner turns green when the model has loaded. Loading happens in the background at startup and takes a few seconds.

• Open any dataset from the Demo datasets gallery. Each one opens set up for the analysis that shows it off best.

• To refresh the real datasets from their original sources, run .venv/bin/python webapp/fetch_real_datasets.py --refresh on macOS or .venv\Scripts\python.exe webapp\fetch_real_datasets.py --refresh on Windows.

• To keep the weights somewhere else, set TIMESFM_MODEL_DIR to that folder before starting. The launcher and download_model.py both use it.

Troubleshooting

• "Checkpoint missing" in the status bar: the weights didn't finish downloading. Run the launcher again, or run download_model.py; the download resumes where it stopped.

• Installing on a machine without a keyboard or terminal (scripted setup): run download_model.py --yes to accept the licence without the prompt.

• Port 7863 already in use: another copy of the studio is running. Close it, or edit the port in the launcher.

• CUDA not used on Windows: check with .venv\Scripts\python.exe -c "import torch; print(torch.cuda.is_available())". If it prints False, redo step 4 with the command from pytorch.org.

The original TimesFM README from Google Research follows.

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.

• (NEW!) TimesFM 3.0 Checkpoint: google/timesfm-3.0-pytorch.

• Checkpoints (up to 2.5): TimesFM Hugging Face Collection.

• Google Research blog (New blog post for TimesFM 3.0 coming soon!).

• 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 — 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:

• 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

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:

• 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

From PyPI

# Install TimesFM with PyTorch
pip install timesfm[torch]

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)

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)