google-research/timesfm README (TimesFM 3.0 checkpoint, timesfm-non-commercial-license-v1.0)

GitHub - google-research/timesfm: TimesFM (Time Series Foundation Model) is a pretrained time-series foundation model developed by Google Research for time-series forecasting. · GitHub
Skip to content
Navigation Menu Sign in Appearance settings Platform AI CODE CREATION GitHub Copilot Write better code with AI GitHub Copilot app Direct agents from issue to merge MCP Registry Integrate external tools DEVELOPER WORKFLOWS Actions Automate any workflow Codespaces Instant dev environments Issues Plan and track work Code Review Manage code changes Code Quality Enforce quality at merge APPLICATION SECURITY GitHub Advanced Security Find and fix vulnerabilities Code security Secure your code as you build Secret protection Stop leaks before they start EXPLORE Why GitHub Documentation Blog Changelog Marketplace View all features Solutions BY COMPANY SIZE Enterprises Small and medium teams Startups Nonprofits BY USE CASE App Modernization DevSecOps DevOps CI/CD View all use cases BY INDUSTRY Healthcare Financial services Manufacturing Government View all industries View all solutions Resources EXPLORE BY TOPIC AI Software Development DevOps Security View all topics EXPLORE BY TYPE Customer stories Events & webinars Ebooks & reports Business insights GitHub Skills SUPPORT & SERVICES Documentation Customer support Community forum Trust center Partners View all resources Open Source COMMUNITY GitHub Sponsors Fund open source developers PROGRAMS Security Lab Maintainer Community GitHub Stars Archive Program REPOSITORIES Topics Trending Collections Enterprise ENTERPRISE SOLUTIONS Enterprise platform AI-powered developer platform AVAILABLE ADD-ONS GitHub Advanced Security Enterprise-grade security features Copilot for Business Enterprise-grade AI features Premium Support Enterprise-grade 24/7 support Pricing Search / Sign in Sign up Appearance settings
You signed in with another tab or window. Reload to refresh your session.
You signed out in another tab or window. Reload to refresh your session.
You switched accounts on another tab or window. Reload to refresh your session.
Dismiss alert
{{ message }}
Uh oh!
There was an error while loading. Please reload this page .
google-research
/
timesfm
Public
Notifications
You must be signed in to change notification settings
Fork
2.8k
Star
28.6k
Code
Issues
146
Pull requests
79
Discussions
Actions
Security and quality
0
Insights
Additional navigation options
Code
Issues
Pull requests
Discussions
Actions
Security and quality
Insights
master Branches Tags Go to file Code Open more actions menu Latest commit   History 355 Commits 355 Commits Folders and files Name Name Last commit message Last commit date .github/ workflows .github/ workflows     src src     tests tests     timesfm-forecasting timesfm-forecasting     timesfm3-usage timesfm3-usage     v1 v1     .gitattributes .gitattributes     .gitignore .gitignore     AGENTS.md AGENTS.md     LICENSE LICENSE     README.md README.md     pyproject.toml pyproject.toml     requirements.txt requirements.txt     View all files Repository files navigation README Apache-2.0 license More items 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:
✅ Flax version of the model for faster inference.
✅ Covariate support via XReg (see Oct. 2025 update).
✅ Documentation, examples, and agent skill (see timesfm-forecasting/ ).
✅ Fine-tuning example with LoRA via HuggingFace Transformers + PEFT (see
timesfm-forecasting/examples/finetuning/ ).
✅ Unit tests for core layers, configs, and utilities (see tests/ ).
Install
From PyPI
# Install TimesFM with PyTorch
pip install timesfm[torch]
Local Install
Clone the repository:
git clone https://github.com/google-research/timesfm.git
cd timesfm
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)
About TimesFM (Time Series Foundation Model) is a pretrained time-series foundation model developed by Google Research for time-series forecasting. research.google/blog/a-decoder-only-foundation-model-for-time-series-forecasting/ Resources Readme Apache-2.0 license Activity Custom properties Stars 28.6k stars Watchers 191 watching Forks 2.8k forks Report repository Releases Packages Used by Contributors Languages
Footer
© 2026 GitHub, Inc.
Footer navigation
Terms
Privacy
Security
Status
Community
Docs
Contact
Manage cookies
Do not share my personal information
You can’t perform that action at this time.