🔴 Advanced ⚙️ Type: Time Series Foundation Model / AI Forecasting 💸 Free & Open Source (Apache-2.0) ⭐ 21,000+ GitHub Stars
What is TimesFM?
TimesFM (Time Series Foundation Model) is a groundbreaking decoder-only AI foundation model developed by Google Research. Instead of processing natural language text like ChatGPT or Gemini, TimesFM is designed entirely around the mathematical language of time. It treats groups of continuous data points (known as “patches”) like tokens, having been pre-trained on a massive, diverse corpus of over 100 billion real-world time-points.
The magic of TimesFM lies in its zero-shot forecasting capability. Historically, if a company wanted to predict product demand or server workloads, data scientists had to gather historical data and explicitly train a bespoke statistical model (like ARIMA) or a deep learning model for that specific task. TimesFM changes the paradigm: you simply feed it a raw sequence of past data, and its generalized understanding of trends, seasonality, and variance allows it to instantly and accurately predict the future out-of-the-box.
With the release of TimesFM 2.5, Google massively optimized the architecture. It shrank the model to a highly efficient 200-million parameters, removed the need to manually specify data frequency, added support for external variables (XReg covariates), and expanded its context window to analyze up to 16,000 historical data points at once.
Who is it for?
- Quantitative Analysts and Traders building algorithmic statistical arbitrage systems or predicting stock, crypto, and commodity price movements.
- Supply Chain and Retail Managers forecasting inventory demand across millions of SKUs without needing to train and maintain individual predictive models for each product.
- DevOps and MLOps Engineers building predictive autoscalers that dynamically allocate Kubernetes pods or cloud servers based on forecasted network traffic and workloads.
- AI Agents and Application Developers providing their LLM agents with deterministic forecasting tools via Function Calling and Model Context Protocol (MCP) servers.
What makes it special?
- State-of-the-Art Zero-Shot Generalization — On major forecasting benchmarks, TimesFM routinely matches or beats explicitly trained supervised models (like PatchTST or DeepAR) and classical statistical methods without looking at the training data.
- Patch-Based Parallel Inference — Standard LLMs predict text one word at a time, which is slow. TimesFM groups data into patches, allowing it to predict entire segments of the future (up to 128 time-points) simultaneously, resulting in blisteringly fast inference speeds.
- Continuous Quantile Forecasting — It doesn’t just give you a single “point” guess for the future. The TimesFM 2.5 quantile head generates upper and lower boundary estimates, giving you the mathematical probability and confidence intervals of its predictions.
- Covariate Support (XReg) — You are not limited strictly to historical numbers. You can feed the model external context—such as upcoming holidays, ad spend data, or weather forecasts—to heavily refine its trajectory.
Requirements before you start
TimesFM is a programmatic library meant to be integrated into Python workflows. You will need a standard data science environment:
- Python 3.10+ — The base language requirement. (Using Python 3.10 specifically is highly recommended to avoid dependency conflicts).
- A Machine Learning Backend — You can choose to run the model on either PyTorch (most common) or JAX/Flax (faster for optimized inference).
- Hardware — While the 200M parameter model is small enough to run on a standard CPU, rendering long-horizon forecasts is significantly faster on a CUDA-enabled NVIDIA GPU or Apple Silicon.
Step-by-step installation
Method 1 — Quick Install via PyPI (Recommended)
The easiest way to get started is by installing the pre-packaged library into a fresh virtual environment. Open your terminal and run:
pip install timesfm[torch](If you plan to use external variables and covariates, install the extra dependencies by running: pip install "timesfm[torch,xreg]")
Method 2 — Install from GitHub (For the Latest Features)
If you want to run Google’s fine-tuning examples using LoRA, clone the repository locally using uv or pip:
git clone https://github.com/google-research/timesfm.git
cd timesfm
uv venv
source .venv/bin/activate
uv pip install -e .[torch]Step 3 — Write Your First Forecast Script
Create a new Python file (e.g., forecast.py) and paste the following code to download the TimesFM 2.5 checkpoint from Hugging Face and run a prediction on dummy data:
import torch
import numpy as np
import timesfm
# Optimize matrix multiplication for modern GPUs
torch.set_float32_matmul_precision("high")
# 1. Download and load the 2.5 (200M) model checkpoint
model = timesfm.TimesFM_2p5_200M_torch.from_pretrained("google/timesfm-2.5-200m-pytorch")
# 2. Compile the model configuration
model.compile(
timesfm.ForecastConfig(
max_context=1024,
max_horizon=256,
normalize_inputs=True,
use_continuous_quantile_head=True
)
)
# 3. Create a mock time-series (e.g., 500 days of fluctuating sales)
historical_data = [np.sin(np.linspace(0, 20, 500))]
# 4. Predict the next 60 days
point_forecast, quantile_forecast = model.forecast(
inputs=historical_data,
horizon=60
)
print(f"Zero-Shot Forecasted trajectory: {point_forecast[0]}")
Run the script using python forecast.py. The library will automatically pad the context, run the inference, and return an array of predicted future values!
Common errors and fixes
| Error | What it means | How to fix it |
|---|---|---|
Unexpected keyword argument 'frequency_indicator' | You are looking at older TimesFM 1.0/2.0 tutorials. Version 2.5 completely removed the need to manually declare data frequency. | Remove any frequency arguments from your model initialization parameters. Ensure your timesfm pip package is updated to at least version 2.0.0. |
| JAX dependencies are installed even when using PyTorch | Due to how the library is currently structured, the core timesfm package has a hard dependency on JAX for some internal utility functions. | This is normal and will not stop PyTorch from handling the heavy inference. Just ensure your JAX version does not clash with your CUDA driver versions if you are building strict Docker containers. |
| Out of Memory (OOM) / CUDA Crash | The model is attempting to process an excessively large context window (e.g., 16,000 points) on a GPU with limited VRAM. | In your ForecastConfig, lower the max_context parameter from 16384 to something smaller, like 1024 or 512, which is more than enough context for standard forecasting needs. |
Free vs Paid comparison
| Feature | TimesFM (GitHub Open Source) | TimesFM in Google BigQuery ML |
|---|---|---|
| Software Cost | $0 (Free Apache-2.0 License) | Pay-per-query / Compute costs |
| Setup Effort | ⚠️ Requires Python & hardware management | 🟢 Zero setup (Managed Service) |
| Customization & Fine-Tuning | ✅ Full access to LoRA and model architecture | ❌ Operates via fixed SQL functions (ML.FORECAST) |
| Data Privacy | ✅ Absolute (Runs 100% offline) | ⚠️ Data resides in Google Cloud |
Bottom line: TimesFM is a masterclass in foundation model architecture. By turning time-series forecasting into a zero-shot problem, Google has saved data science teams countless hours of training custom ARIMA or DeepAR models. If you are building a Python-based trading bot, a real estate predictor, or an AI agent, incorporating the open-source TimesFM library is an absolute game-changer.
Alternatives — 3 similar tools
1. Chronos (by Amazon Science)
The primary rival to TimesFM. Chronos takes a fundamentally different approach by tokenizing time-series values into discrete “bins” and feeding them through a standard T5 language model architecture. It is incredibly robust, highly flexible, and performs phenomenally well on zero-shot benchmarks alongside TimesFM.
🔗 github.com/amazon-science/chronos-forecasting
2. Moirai (by Salesforce AI)
A massive Masked Encoder-based Universal Forecasting model. Moirai is specifically designed to handle a wide variety of frequencies and variables across multiple domains simultaneously. It is highly competitive in the foundation model space and heavily utilized in enterprise data architectures.
🔗 github.com/SalesforceAIResearch/uni2ts
3. Lag-Llama
An open-source foundation model built upon the architecture of Meta’s LLaMA. Lag-Llama is a general-purpose univariate probabilistic time-series forecasting model. It is excellent if you specifically want to leverage your existing knowledge of the LLaMA ecosystem and fine-tuning pipelines applied to numerical data.
🔗 github.com/time-series-foundation-models/lag-llama
🚀 Want more free AI tools like this?
We find, test, and write setup guides for the best free and open-source AI tools — so you don’t have to dig through GitHub yourself.Browse Free AI Tools at globalaiforce.com/shop →
📸 Follow us for daily AI tool tips and tutorials: instagram.com/globalaiforce