{"id":4471,"library":"chronos-forecasting","title":"Chronos: Pretrained Models for Time Series Forecasting","description":"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.","status":"active","version":"2.2.2","language":"python","source_language":"en","source_url":"https://github.com/amazon-science/chronos-forecasting","tags":["time series","forecasting","pretrained models","machine learning","deep learning","transformers","chronos-2","zero-shot"],"install":[{"cmd":"pip install 'chronos-forecasting[extras]'","lang":"bash","label":"Recommended installation for Chronos-2"},{"cmd":"pip install chronos-forecasting","lang":"bash","label":"Minimal installation"}],"dependencies":[{"reason":"Required Python version","package":"python","min_version":"3.10"},{"reason":"Data handling (DataFrames)","package":"pandas","optional":false},{"reason":"Core deep learning framework","package":"torch","optional":false},{"reason":"Underlying model architecture, relaxed lower bound in v2.0.1 to >=4.41","package":"transformers","optional":false,"min_version":"4.41"},{"reason":"For plotting and visualization in examples","package":"matplotlib","optional":true}],"imports":[{"symbol":"BaseChronosPipeline","correct":"from chronos import BaseChronosPipeline"},{"symbol":"Chronos2Pipeline","correct":"from chronos import Chronos2Pipeline"},{"note":"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.","wrong":"from chronos import BaseChronosPipeline; pipeline = BaseChronosPipeline.from_pretrained('amazon/chronos-t5-small')","symbol":"ChronosPipeline","correct":"from chronos import ChronosPipeline"}],"quickstart":{"code":"import os\nimport pandas as pd\nimport torch\nimport matplotlib.pyplot as plt\nfrom chronos import BaseChronosPipeline\n\n# Use GPU if available, otherwise CPU\ndevice = 'cuda' if torch.cuda.is_available() else 'cpu'\n# Set CUDA_VISIBLE_DEVICES if using a specific GPU\nos.environ['CUDA_VISIBLE_DEVICES'] = os.environ.get('CUDA_VISIBLE_DEVICES', '0') if device == 'cuda' else ''\n\n# Load the Chronos-2 pipeline\npipeline = BaseChronosPipeline.from_pretrained(\n    \"amazon/chronos-2-small\", \n    device_map=device\n)\n\n# Prepare sample univariate time series data (e.g., air passengers)\ndata = {\n    'timestamp': pd.to_datetime(['1949-01-01', '1949-02-01', '1949-03-01', '1949-04-01', '1949-05-01', '1949-06-01']),\n    'item_id': ['A']*6,\n    'target': [112, 118, 132, 129, 121, 135]\n}\ndf = pd.DataFrame(data)\n\n# Predict next 6 steps (e.g., 6 months)\nprediction_length = 6\nforecast = pipeline.predict(\n    context=df,\n    prediction_length=prediction_length,\n    num_samples=50 # Number of probabilistic samples\n)\n\nprint(f\"Forecast shape: {forecast.shape}\")\nprint(\"First 5 forecast values (median):\")\nprint(forecast.head())\n\n# Optional: Plotting the forecast\nplt.figure(figsize=(10, 6))\nplt.plot(df['timestamp'], df['target'], label='Historical Data', marker='o')\n\n# Convert forecast index to datetime for plotting if needed (it's often relative)\n# For simplicity, we'll plot against a generated date range or use sample indices\nlast_hist_date = df['timestamp'].iloc[-1]\nforecast_dates = pd.date_range(start=last_hist_date + pd.DateOffset(months=1), periods=prediction_length, freq='MS')\n\nplt.plot(forecast_dates, forecast.mean(axis=1), label='Forecast (Mean)', linestyle='--', marker='x')\nplt.fill_between(\n    forecast_dates, \n    forecast.quantile(0.1, axis=1), \n    forecast.quantile(0.9, axis=1), \n    color='blue', alpha=0.2, label='80% Confidence Interval'\n)\n\nplt.xlabel('Date')\nplt.ylabel('Value')\nplt.title('Chronos Forecasting Example')\nplt.legend()\nplt.grid(True)\nplt.show()","lang":"python","description":"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."},"warnings":[{"fix":"Update your code to use `cross_learning` instead of `predict_batches_jointly`.","message":"The 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.","severity":"breaking","affected_versions":">=2.2.0"},{"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.","message":"Earlier 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.","severity":"gotcha","affected_versions":"<2.0.0 (for limitations), >=2.0.0 (for new capabilities)"},{"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.","message":"Models 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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"When 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.","severity":"gotcha","affected_versions":"All versions supporting fine-tuning"}],"env_vars":null,"search_vec":"'-2':33,99 '2.2.2':35 'activ':83 'appli':58 'architectur':28 'art':78 'base':25 'cadenc':87 'capabl':38 'chrono':1,8,32,98 'covari':48 'covariate-inform':47 'deep':95 'develop':84 'divers':63 'eas':70 'expand':37 'famili':15 'focus':68 'forecast':7,20,50,64,90 'foundat':60 'includ':40 'inform':49 'interfac':56 'intuit':55 'iter':31 'languag':26 'latest':30 'learn':94,96 'leverag':22 'librari':12,52 'machin':93 'maintain':81 'model':3,21,27,61,92 'multivari':45 'offer':13 'perform':79 'pretrain':2,17,91 'provid':53 'python':11 'releas':86 'seri':6,19,89 'shot':43,102 'signific':36 'state':75 'state-of-the-art':74 'task':65 'time':5,18,88 'transform':24,97 'transformer-bas':23 'univari':44 'use':72 'version':34 'zero':42,101 'zero-shot':41,100","created_at":"2026-04-12T13:54:04.771026+00:00","updated_at":"2026-04-16T02:07:04.945009+00:00","problems":[{"fix":"Use `from chronos import ChronosPipeline` instead of `from chronos import BaseChronosPipeline`.","cause":"Users attempting to import a legacy or incorrect class name for the Chronos model pipeline. The `chronos-forecasting` library uses `ChronosPipeline` for model inference.","error":"ImportError: cannot import name 'BaseChronosPipeline' from 'chronos'"},{"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.","cause":"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.","error":"OSError: Can't load tokenizer for 'amazon/chronos-t5-large'"},{"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.","cause":"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.","error":"ValueError: Future covariates must have the same frequency as context, found series ... with a different frequency"},{"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.","cause":"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.","error":"AttributeError: 'list' object has no attribute 'test'"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"2.3.1","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/amazon-science/chronos-forecasting","docs":null,"changelog":null,"pypi":"https://pypi.org/project/chronos-forecasting/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["ai-ml","data"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-29","next_check":"2026-07-28","install_tag":null}}