TimesFM: A Decoder-Only Time-Series Foundation Model for Forecasting

1. Overview

• TimesFM, short for Time Series Foundation Model, is a pretrained model developed by Google Research designed for time-series forecasting at scale.
• Conceptual foundation: TimesFM is described as a decoder-only foundation model tailored for forecasting tasks, enabling generation of future values and probabilistic (quantile) forecasts from historical inputs.
• Core reference: The model is introduced in the paper titled A decoder-only foundation model for time-series forecasting, presented at ICML 2024 with an arXiv identifier 2310.10688.
• Access and checkpoints: A dedicated collection of TimesFM checkpoints exists on Hugging Face, enabling researchers and practitioners to load and experiment with pretrained weights.
• Official discourse: The Google Research blog provides an overview of TimesFM as a decoder-only approach for time-series forecasting, offering context and motivation for the design choices.
• Practical ecosystem: TimesFM is embedded in a broader ecosystem of Google 1P (first-party) products and services, underscoring its applicability across enterprise analytics, productivity tools, and platform integrations.
• Primary deployment channels highlighted:
• BigQuery ML: Enterprise-grade SQL queries using TimesFM as the forecasting engine, emphasizing scalability and reliability for data warehouse workflows.
• Google Sheets: Forecast data integration into connected spreadsheets, enabling daily planning and dashboarding within familiar spreadsheet environments.
• Vertex Model Garden: A dockerized endpoint suitable for agent-like calls in experimentation and deployment; note that this open version is not an officially supported Google product.
• Version landscape:
• Latest model: TimesFM 2.5, representing the most up-to-date capabilities and improvements.
• Archived versions: 1.0 and 2.0, with code archived under the v1 subdirectory for historical reference and compatibility.
• Availability note: Users can install older iterations via pip; for example, pip install timesfm==1.3.0 loads the 1.3-era release.
• Summary takeaway: TimesFM represents a concerted effort to bring highly capable, decoder-oriented time-series forecasting to both research and production environments, with attention to model size, context window, quantile forecasting, and integrations with Google’s data ecosystem.

1. Core Concepts and Architecture

• Decoder-only design: TimesFM is built as a decoder-centric architecture optimized for forecasting tasks, where generation of future time steps is conditioned on past observations and optional covariates.
• Forecasting outputs: The model supports point forecasts (single-valued predictions) and probabilistic forecasts across quantiles, enabling users to assess uncertainty and construct prediction intervals.
• Context length and horizon:
• TimesFM 2.5 scales context windows to as much as 16k time steps, a substantial increase over earlier baselines.
• Horizon support includes continuous quantile forecasting extending to long horizons (up to 1k steps) via an optional quantile head.
• Parameter efficiency and scaling:
• The 2.5 release reduces parameter count to 200 million, down from 500 million in earlier configurations, balancing performance with efficiency.
• The model eliminates certain legacy indicators (for example, a frequency indicator) to streamline inputs and forecasting behavior.
• Covariates and conditioning:
• Covariate support via XReg has been introduced, enabling richer conditioning signals such as exogenous variables, seasonality indicators, or external covariates to influence forecasts.
• Computation and inference:
• A flax-based Flax version exists for faster inference, contributing to lower latency in real-time or near-real-time forecasting scenarios.
• Quantile head and crossing:
• The optional 30 million-parameter quantile head enables continuous quantile forecasting across a broad horizon, improving probabilistic estimates and calibration.
• The model incorporates mechanisms to fix quantile crossing and other stability concerns in the quantile forecasts.
• Practical implications:
• The decoupled design of a quantile head, covariates, and a compact parameter footprint makes TimesFM attractive for datasets with long histories, varying frequencies, and diverse feature sets.
• The pruning of certain indicators and the emphasis on a decoder-centric forecasting loop aligns with modern autoregressive and autoregressive-like forecasting paradigms.

1. Model Versions and Access

• Latest version:
• TimesFM 2.5 stands as the current release, incorporating multiple improvements over prior versions.
• Core improvements compared to TimesFM 2.0 include a smaller parameter budget, longer context, and expanded forecasting capabilities.
• Archived versions:
• TimesFM 1.0 and TimesFM 2.0 exist as historical releases; the code for these versions is archived under a subdirectory named v1 to preserve compatibility and reproducibility.
• How to access older versions:
• The ecosystem provides a sanctioned path to load older iterations through package installation, for example:
  • pip install timesfm==1.3.0 to install the 1.3-era variant.
• Version evolution at a glance:
• 2.5 introduced key shifts such as reduced parameters (200M), extended context (up to 16k), a quantile head enabling long-horizon probabilistic forecasts, and removal of a frequency indicator.
• Subsequent improvements post-2.5 include Flax-based acceleration, covariate support, enhanced documentation and example workflows, and unit tests to bolster reliability.
• Significance for users:
• The versioning narrative helps practitioners select an appropriate configuration based on hardware constraints, desired forecast horizon, and whether covariates or quantile heads are required for their use case.

1. Update Timeline and Highlights

• Apr 9, 2026: Fine-tuning example and testing enhancements
• Added a fine-tuning example using HuggingFace Transformers in combination with PEFT (LoRA) to facilitate parameter-efficient fine-tuning workflows.
• New example directory: timesfm-forecasting/examples/finetuning/.
• Unit tests were added (tests/) to improve reliability and regression safety.
• Community contributions acknowledged, with thanks to contributors such as Kashif and darkpowerxo for fixes and improvements.
• Mar 19, 2026: AGENTS integration and skill documentation
• Added AGENTS support, broadening automation and agent-like capabilities for forecasting workflows.
• TimesFM SKILL.md surfaced, documenting agent-oriented capabilities and usage patterns in timesfm-tree ecosystems.
• Oct 29, 2025: Covariate support via XReg
• Covariate support was reintroduced for TimesFM 2.5 through XReg, enabling users to incorporate external features directly into forecasts.
• Sept 15, 2025: TimesFM 2.5 release
• Core technical changes:
  • Parameter budget reduced to 200M from 500M, enhancing efficiency.
  • Context length expanded to 16k, enabling modeling of long-range dependencies.
  • Continuous quantile forecasting extended up to horizon 1k via an optional quantile head (approximately 30M parameters in that head).
  • Frequency indicator removed to simplify the input schema.
  • Introduction of additional forecasting flags to tune behavior and outputs.
• Notable post-release improvements:
  • Flax version released for faster inference, leveraging modern JAX/Flax tooling.
  • Covariate support via XReg implemented, enabling richer conditioning signals.
  • Documentation improvements, examples, and agent skill (see timesfm-forecasting).
  • Fine-tuning example using LoRA (PEFT) via HuggingFace Transformers added (see timesfm-forecasting/examples/finetuning/).
  • Unit tests introduced for core layers, configurations, and utilities (see tests/).
• Installation and setup updates
• Instructions provided to clone the repository, set up virtual environments, and install dependencies for torch, flax, or xreg backends.
• Guidance links included for installing PyTorch and JAX/Flax backends depending on operating system, hardware (CPU, GPU, TPU), or Apple Silicon.
• Overall trajectory
• The release and update cadence reflect a pattern of reducing footprint, extending context, broadening conditioning, and providing robust tooling and tests for the community.
• The ecosystem emphasizes both production-grade integrations (BigQuery ML, Google Sheets) and research-friendly experimentation (LoRA fine-tuning, AGENTS, unit tests).

1. Install and Setup

• Initial steps:
• Clone the TimesFM repository to obtain the source and example configurations.
• Create a dedicated Python virtual environment to isolate dependencies and reproducibility.
• Activate the virtual environment to set up a clean Python workspace.
• Dependency installation:
• Install the package in editable mode with an optional backend:
  • For PyTorch: install the package with torch support.
  • For Flax: install the package with flax support.
  • For XReg: install the package with xreg support, as needed for covariate conditioning.
• Backend considerations:
• Optional installation of your preferred PyTorch or JAX backend is recommended, based on your OS and available accelerators (CPU, GPU, TPU, or Apple Silicon).
• Access to CUDA-enabled GPUs can significantly accelerate training and inference for larger workloads.
• Practical commands (illustrative, not executable here):
• Clone and enter the repository:
  • git clone https://github.com/google-research/timesfm.git
  • cd timesfm
• Create and activate a virtual environment:
  • uv venv
  • source .venv/bin/activate
• Install the package in editable mode with desired backends:
  • uv pip install -e .[torch]
  • uv pip install -e .[flax]
  • uv pip install -e .[xreg]
• Optional accelerators and configurations:
• Depending on your platform, you may choose a CPU-only setup or a GPU/TPU-accelerated configuration.
• The installation instructions reference official guides for PyTorch and JAX to tailor the environment for your hardware.

1. Quick Start Code Example

• A representative Python snippet demonstrates loading a pretrained TimesFM model and configuring a forecast run:
• Import the necessary libraries: torch, numpy, and timesfm.
• Set matrix-multiplication precision to maximize numerical stability: torch.setfloat32matmul_precision("high").
• Load the pretrained model: TimesFM2p5200Mtorch.frompretrained("google/timesfm-2.5-200m-pytorch").
• Build a forecast configuration with sensible defaults:
  • max_context: 1024
  • max_horizon: 256
  • normalize_inputs: True
  • usecontinuousquantile_head: True
  • forceflipinvariance: True
  • inferispositive: True
  • fixquantilecrossing: True
• Run a forecast for a modest horizon:
  • pointforecast, quantileforecast = model.forecast( horizon=12, inputs=[np.linspace(0, 1, 100), np.sin(np.linspace(0, 20, 67))], )
• Inspect shapes to confirm outputs:
  • point_forecast.shape yields (2, 12)
  • quantile_forecast.shape yields (2, 12, 10)
• What the outputs represent:
• point_forecast provides the central predictions for the next 12 steps for two series (as indicated by the first dimension).
• quantile_forecast provides 10 quantiles (from the 10th to the 90th percentile by default, plus a mean) across the 12 horizons for the two series, enabling probabilistic interpretation.
• Practical note:
• The example illustrates a minimal end-to-end flow from loading a pretrained model to generating forecast outputs, highlighting how inputs are structured and how forecasts are shaped.

1. Integrations with Google 1P Products and Ecosystem

• BigQuery ML integration:
• TimesFM powers enterprise-grade time-series forecasting within SQL workflows, enabling scalable forecasting directly in BigQuery environments.
• This integration supports large-scale analytics use cases where data resides in data warehouses, with forecasts consumed by downstream BI and analytics pipelines.
• Google Sheets integration:
• Forecast data can be surfaced in connected Google Sheets, enabling analysts and business users to view and manipulate forecast results in familiar spreadsheet tools.
• This connection can support daily planning, scenario analysis, and lightweight forecasting dashboards without leaving the Sheets interface.
• Vertex Model Garden:
• A Dockerized endpoint workflow is available via Vertex Model Garden for agent-like calling, facilitating easy experimentation and deployment in a containerized environment.
• Important caveat: The open version described in the materials is not an officially supported Google product, so production usage should consider the supported stacks and recommended deployment paths.
• Open ecosystem and community:
• TimesFM’s presence on Hugging Face consolidates a community around model sharing, evaluation, and experimentation.
• Blog posts and official documentation provide guidance for practitioners integrating TimesFM into their data pipelines and model serving stacks.

1. Community, Documentation, and Resources

• Documentation and tutorials:
• The TimesFM project includes documentation, example workflows, and a dedicated timesfm-forecasting folder with guidance on forecasting tasks.
• The SKILL.md document presents agent-like capabilities and usage considerations, expanding how teams can compose forecasting workflows around TimesFM.
• Community contributions:
• The project acknowledges and incorporates community fixes and enhancements, with contributor shoutouts (e.g., Kashif, darkpowerxo, borealBytes) for improvements such as AGENTS support and covariate integration.
• Tests and quality assurance:
• Unit tests have been introduced to validate core layers, configuration handling, and utility functions, reducing risk when extending or deploying TimesFM in new contexts.
• Fine-tuning and experimentation:
• Fine-tuning workflows have been demonstrated using HuggingFace Transformers and PEFT (LoRA), enabling practitioners to adapt TimesFM to domain-specific data while keeping compute costs manageable.
• Licensing and usage notes:
• The TimesFM project emphasizes reproducibility and openness, with access through open-source repositories and community channels; practitioners should review license terms and repository guidelines for usage in commercial settings.

1. Visual Aids and Images

• Availability of images:
• The input material provided for this description does not include image assets or diagrams.
• What visual references would illuminate:
• Architecture diagram of TimesFM showing the decoder-only transformer stack, the input feature pipeline (historical time series, optional covariates), and the quantile head for probabilistic forecasts.
• Data flow diagram illustrating how a user provides historical inputs, covariates via XReg, and how the model outputs point forecasts and quantiles.
• A comparison chart highlighting TimesFM 2.5 versus earlier versions (parameters, context length, horizon, and quantile head).
• A usage workflow screenshot for BigQuery ML, Google Sheets integration, and Vertex Model Garden deployments to demonstrate practical deployment paths.
• If images are supplied in the future:
• The description could incorporate image captions aligned with the sections above to provide readers with visual anchors to the textual content.

1. References and External Links

• Paper and academic references:
• A decoder-only foundation model for time-series forecasting, arXiv:2310.10688, ICML 2024.
• Checkpoints and model collections:
• TimesFM Hugging Face Collection for the official checkpoints and releases.
• Official communications:
• Google Research blog post detailing TimesFM’s decoder-only design and forecasting capabilities.
• Enterprise and productivity integrations:
• BigQuery ML documentation for TimesFM-based forecasting in SQL workflows.
• Google Sheets blog post describing forecast data in connected sheets using TimesFM.
• Model deployment and ecosystem:
• Vertex Model Garden entry for TimesFM: a dockerized endpoint for agent-like use.
• Versioning and installation notes:
• TimesFM 2.5 as the latest model version.
• Archived versions 1.0 and 2.0, with subdirectory v1 for older code.
• Pip installation path for older versions (e.g., pip install timesfm==1.3.0).
• Developer and usage resources:
• timesfm-forecasting directory for examples, including finetuning and agent-related workflows.
• tests/ directory for unit tests validating essential components.
• timesfm SKILL.md and AGENTS.md references for agent-based and skill-oriented usage.

Images and visual references note: No images were attached in the provided input. If you supply diagrams or figures, I can integrate them into the structure above with descriptive captions aligned to the corresponding sections.