{"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":"en","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,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}