Registry / ai-ml / chronos-forecasting

chronos-forecasting

JSON →
library2.3.1pypypi✓ verified 27d ago

Chronos is a Python library offering a family of pretrained time series forecasting models, leveraging transformer-based language model architectures. The latest iteration, Chronos-2 (version 2.2.2), significantly expands capabilities to include zero-shot univariate, multivariate, and covariate-informed forecasting. The library provides an intuitive interface for applying these foundation models to diverse forecasting tasks, with a focus on ease of use and state-of-the-art performance. It maintains an active development and release cadence.

pip install 'chronos-forecasting[extras]'
INSTALL
IMPORT
SIG · CHRONOS-FORECASTIN
C
chronos-forecasting
ai-mlpythonv2.3.1
Install
79.3s avg
Import
18890ms
Disk
5427MB
Pass rate
1/ 10
Env Coverage1 / 10
glibc
3.9–3.13
musl
3.9–3.13
Install & Compatibility
Where this runs
tested against v2.3.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
glibc
py 3.10
✕ build_error
1/2 runs
py 3.11
✕ build_error
1/2 runs
py 3.12
✕ build_error
1/2 runs
py 3.13
✕ build_error
✓ 79.25s
py 3.9
✕ build_error
✕ timeout
5427MB installed
● package 5427MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

BaseChronosPipeline
✓ from chronos import BaseChronosPipeline
Chronos2Pipeline
✓ from chronos import Chronos2Pipeline
ChronosPipeline
✓ from chronos import ChronosPipeline
✗ from chronos import BaseChronosPipeline; pipeline = BaseChronosPipeline.from_pretrained('amazon/chronos-t5-small')
While 'ChronosPipeline' is still available, 'BaseChronosPipeline.from_pretrained("amazon/chronos-2")' or 'Chronos2Pipeline' is the current recommended way to load Chronos-2 models for advanced features like multivariate forecasting and covariates.

This quickstart demonstrates how to load a pretrained Chronos-2 model and generate a probabilistic forecast for a univariate time series. It prepares a sample Pandas DataFrame, uses the `predict` method to obtain future predictions, and optionally visualizes the historical data along with the forecasted mean and an 80% confidence interval. Ensure 'chronos-forecasting[extras]' is installed for full functionality. A GPU is recommended for faster inference, though CPU is supported.

import os import pandas as pd import torch import matplotlib.pyplot as plt from chronos import BaseChronosPipeline # Use GPU if available, otherwise CPU device = 'cuda' if torch.cuda.is_available() else 'cpu' # Set CUDA_VISIBLE_DEVICES if using a specific GPU os.environ['CUDA_VISIBLE_DEVICES'] = os.environ.get('CUDA_VISIBLE_DEVICES', '0') if device == 'cuda' else '' # Load the Chronos-2 pipeline pipeline = BaseChronosPipeline.from_pretrained( "amazon/chronos-2-small", device_map=device ) # Prepare sample univariate time series data (e.g., air passengers) data = { 'timestamp': pd.to_datetime(['1949-01-01', '1949-02-01', '1949-03-01', '1949-04-01', '1949-05-01', '1949-06-01']), 'item_id': ['A']*6, 'target': [112, 118, 132, 129, 121, 135] } df = pd.DataFrame(data) # Predict next 6 steps (e.g., 6 months) prediction_length = 6 forecast = pipeline.predict( context=df, prediction_length=prediction_length, num_samples=50 # Number of probabilistic samples ) print(f"Forecast shape: {forecast.shape}") print("First 5 forecast values (median):") print(forecast.head()) # Optional: Plotting the forecast plt.figure(figsize=(10, 6)) plt.plot(df['timestamp'], df['target'], label='Historical Data', marker='o') # Convert forecast index to datetime for plotting if needed (it's often relative) # For simplicity, we'll plot against a generated date range or use sample indices last_hist_date = df['timestamp'].iloc[-1] forecast_dates = pd.date_range(start=last_hist_date + pd.DateOffset(months=1), periods=prediction_length, freq='MS') plt.plot(forecast_dates, forecast.mean(axis=1), label='Forecast (Mean)', linestyle='--', marker='x') plt.fill_between( forecast_dates, forecast.quantile(0.1, axis=1), forecast.quantile(0.9, axis=1), color='blue', alpha=0.2, label='80% Confidence Interval' ) plt.xlabel('Date') plt.ylabel('Value') plt.title('Chronos Forecasting Example') plt.legend() plt.grid(True) plt.show()
Debug
Known issues
breakingThe method `predict_batches_jointly` was renamed to `cross_learning` in Chronos-2, starting with v2.2.0. Direct calls to the old method will fail.
fix
Update your code to use `cross_learning` instead of `predict_batches_jointly`.
affects: >=2.2.0
gotchaEarlier Chronos (v1.x) and Chronos-Bolt models were primarily designed for univariate forecasting and did not natively support multivariate time series or covariates. Chronos-2, released with v2.x, introduces native support for univariate, multivariate, and covariate-informed forecasting (past-only, known-future, real-valued, categorical). Users upgrading from v1.x or expecting these capabilities must use Chronos-2 models.
fix
Ensure you are using `chronos-forecasting>=2.0` and load a Chronos-2 specific model (e.g., `amazon/chronos-2-small`) via `BaseChronosPipeline.from_pretrained` or `Chronos2Pipeline` for multivariate and covariate-informed tasks.
affects: <2.0.0 (for limitations), >=2.0.0 (for new capabilities)
gotchaModels may struggle with time series data where the variance is very small compared to the mean (e.g., cumulative count data), potentially leading to precision loss and 'wonky' predictions. This is particularly noted for series with high mean and low variability.
fix
Consider preprocessing such time series by applying a shift (subtracting the minimum value) before passing them to the model, and then applying the inverse shift to the resulting forecasts. Refer to GitHub discussions for examples.
affects: All versions
gotchaWhen fine-tuning Chronos models on custom datasets, out-of-the-box configurations (e.g., default `max_steps` or `learning_rate`) may lead to poor performance. Effective fine-tuning often requires careful hyperparameter tuning and understanding of the training pipeline.
fix
Consult the official fine-tuning tutorials and experiment with `training_data_paths`, `context_length`, `prediction_length`, `max_steps`, `per_device_train_batch_size`, and `learning_rate` based on your dataset characteristics.
affects: All versions supporting fine-tuning
Errors
Common errors & fixes
ImportError: cannot import name 'BaseChronosPipeline' from 'chronos'
Users attempting to import a legacy or incorrect class name for the Chronos model pipeline. The `chronos-forecasting` library uses `ChronosPipeline` for model inference.
fix
Use `from chronos import ChronosPipeline` instead of `from chronos import BaseChronosPipeline`.
OSError: Can't load tokenizer for 'amazon/chronos-t5-large'
This error occurs when the system attempts to load the Chronos model using a tokenizer designed for text-based Large Language Models (like T5), or when there are issues with the model files not being correctly located or recognized as a time series model within a specific deployment environment (e.g., AWS SageMaker). Chronos models tokenize time series numerically, not with a text tokenizer.
fix
Ensure you are using `ChronosPipeline.from_pretrained("amazon/chronos-t5-large", ...)` and that the environment is correctly set up for the `chronos-forecasting` library, especially if deploying to platforms like SageMaker, which might have default assumptions for text LLMs. Verify model files are accessible if loading locally or from a private hub.
ValueError: Future covariates must have the same frequency as context, found series ... with a different frequency
This `ValueError` indicates that the time frequency of the `future_df` (dataframe containing future covariates) does not match the time frequency inferred from the `context` (historical data) provided to the forecasting function. It can also occur if the `future_df` is too short to infer a reliable frequency.
fix
Ensure that both your historical data (`context`) and future covariates (`future_df`) are indexed with consistent time frequencies (e.g., daily, hourly) and that `future_df` has at least 3 timesteps for frequency inference. Pre-process your data to align frequencies or fill missing timestamps before passing it to the model.
AttributeError: 'list' object has no attribute 'test'
This `AttributeError` typically arises when a user attempts to call a `.test` attribute or method on a Python `list` object, where they intended to use it on a specific data structure or object (e.g., a custom dataset object or a pandas DataFrame) that is expected to have such an attribute. In the context of Chronos, this might happen during dataset splitting or evaluation if a list is mistakenly treated as a dataset object.
fix
Verify that the `dataset` object you are trying to split or access is indeed an object with a `.test` attribute (e.g., a `TimeSeriesDataset` or a properly structured DataFrame), and not just a raw Python `list`. Ensure proper data loading and conversion to the expected `chronos-forecasting` or `autogluon-timeseries` data format before attempting dataset operations.
Upgrade
Version history
2.3.1latest on PyPI · released Jul 2, 2026
Audit
Dependencies
pythonrequiredRequired Python version
pandasrequiredData handling (DataFrames)
torchrequiredCore deep learning framework
transformersrequiredUnderlying model architecture, relaxed lower bound in v2.0.1 to >=4.41
matplotliboptionalFor plotting and visualization in examples
Agent activity
65 hits · last 30 days
node
58
Amazon
1
OpenAI (training)
1
Resources
chronos-forecasting — pip install chronos-forecasting · libregistry