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
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.fixUpdate 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.fixEnsure 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.fixConsider 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.fixConsult 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.
fixUse `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.
fixEnsure 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.
fixEnsure 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.
fixVerify 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