Registry / ai-ml / gluonts

gluonts

JSON →
library0.17.0pypypi✓ verified 23d ago

GluonTS is a Python toolkit for probabilistic time series modeling, providing facilities for loading datasets, defining models, training them, and making predictions. It supports various deep learning backends, with PyTorch being the currently recommended and most actively developed one. The library is actively maintained with frequent minor releases, currently at version 0.16.2.

pip install gluonts[torch]
INSTALL
IMPORT
SIG · GLUONTS
G
gluonts
ai-mlpythonv0.17.0
Install
46.8s avg
Import
1458ms
Disk
5094MB
Pass rate
4/ 10
Env Coverage4 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v0.17.0 · 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
1/2 runs
✓ 53.6s
py 3.11
1/2 runs
✓ 48.3s
py 3.12
1/2 runs
✓ 43.6s
py 3.13
1/2 runs
✓ 41.65s
py 3.9
✕ build_error
1/2 runs
5094MB installed
● package 5094MB
Code
Verified usage

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

ListDataset
from gluonts.dataset.common import ListDataset
SimpleFeedForwardEstimator
from gluonts.torch.model.simple_feedforward import SimpleFeedForwardEstimator
Trainer
from pytorch_lightning import Trainer
from gluonts.torch.model.predictor import Trainer
Since GluonTS v0.10.x, the Trainer is often imported directly from `pytorch_lightning` when using PyTorch models, rather than from GluonTS's internal wrappers. Ensure `pytorch-lightning` is installed and compatible.
make_evaluation_predictions
from gluonts.evaluation import make_evaluation_predictions
MSE
from gluonts.evaluation.backtest import make_evaluation_predictions, backtest_metrics
Metrics like MSE are typically accessed via `backtest_metrics` after evaluation, not imported directly as a class.
freqstr_to_timedelta
from gluonts.time_feature.util import freqstr_to_timedelta
Useful for understanding time frequency strings.

This quickstart demonstrates how to create a simple dataset, define and train a `SimpleFeedForwardEstimator` using the PyTorch backend, make predictions, and evaluate the model using `gluonts.evaluation`.

from gluonts.dataset.common import ListDataset from gluonts.torch.model.simple_feedforward import SimpleFeedForwardEstimator from pytorch_lightning import Trainer from gluonts.evaluation import make_evaluation_predictions, Evaluator import pandas as pd import numpy as np # 1. Prepare Data target_data = np.random.rand(100) # Dummy time series data start_date = pd.Timestamp("2023-01-01", freq="H") data_entry = { "start": start_date, "target": target_data, "item_id": "item_A" } training_data = ListDataset([data_entry], freq="H") # For evaluation, we need to split data into past and future # In a real scenario, you'd have separate test data or perform backtesting prediction_length = 24 full_data_entry = { "start": pd.Timestamp("2023-01-01", freq="H"), "target": np.concatenate([np.random.rand(80), np.random.rand(24)]), # 80 for training, 24 for future "item_id": "item_B" } # Simulate a test dataset by cutting off the prediction_length from the full series test_data = ListDataset([{ "start": full_data_entry["start"], "target": full_data_entry["target"][:-prediction_length], "feat_static_cat": [0], "item_id": full_data_entry["item_id"] }], freq="H") # 2. Define Estimator estimator = SimpleFeedForwardEstimator( prediction_length=prediction_length, context_length=prediction_length * 2, trainer=Trainer(max_epochs=5, enable_checkpointing=False, enable_progress_bar=False, logger=False), num_hidden_dimensions=[10, 10] ) # 3. Train the model predictor = estimator.train(training_data=training_data) # 4. Make Predictions forecast_it, ts_it = make_evaluation_predictions( dataset=test_data, predictor=predictor, num_samples=100 ) forecasts = list(forecast_it) ts = list(ts_it) # 5. Evaluate evaluator = Evaluator(quantiles=[0.1, 0.5, 0.9]) agg_metrics, item_metrics = evaluator(ts, forecasts, num_series=len(test_data)) print("Aggregated metrics:", agg_metrics) print("First forecast (mean):") print(forecasts[0].mean)
Debug
Known issues
breakingThe `pytorch-lightning` dependency often requires specific version alignment with GluonTS releases. Mismatched versions can lead to runtime errors, especially during training. For example, v0.16.0 included a `pytorch lightning compat` update.
fix
Always check the official `pyproject.toml` or `setup.py` for the recommended `pytorch-lightning` version for your GluonTS installation. If issues arise, try downgrading or upgrading `pytorch-lightning` to the version specified by GluonTS.
affects: 0.10.x onwards, especially across minor GluonTS versions
deprecatedThe MXNet backend (`gluonts.mx`) is less actively maintained and developed compared to the PyTorch backend (`gluonts.torch`). New models and features are primarily added to the PyTorch ecosystem.
fix
For new projects or when seeking the latest features and best support, strongly consider using `gluonts[torch]` and its associated models and utilities.
affects: 0.15.x onwards
gotchaIn older versions, `freq` string parsing could be inconsistent, leading to errors with certain frequency specifications or custom datasets. While fixed in v0.16.0, this was a common source of data loading issues.
fix
Ensure `freq` strings conform to pandas frequency aliases (e.g., 'H', 'D', 'W', 'M', 'min'). For custom frequencies, verify against pandas documentation. Upgrade to 0.16.0 or later to benefit from fixes.
affects: <0.16.0
gotchaWhen constructing `PandasDataset` from `pandas.DataFrame.groupby` operations, a `FutureWarning` could be raised if `observed=True` was not explicitly passed to `groupby`. This was fixed in v0.16.1.
fix
If using older versions or encountering this warning, explicitly pass `observed=True` to `DataFrame.groupby()` calls when preparing data for `PandasDataset`.
affects: <0.16.1
gotchaThe `rpy2` dependency, used for R-based models, was capped at a specific version in v0.16.2 (`rpy2<3.5.11,>=3.4.5`). Mismatched `rpy2` versions can lead to installation failures or runtime errors when using R models.
fix
If you install `gluonts[r]`, ensure `rpy2` adheres to the specified version range. If encountering issues, try installing `rpy2` explicitly to the compatible version before installing `gluonts[r]`.
affects: 0.16.2 onwards
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'gluonts.torch.modules.loss'
This error occurs because the import paths for certain modules, especially those related to PyTorch backend components like loss functions or distribution outputs, have changed in newer versions of GluonTS due to internal refactoring.
fix
Update your import statements to reflect the current module structure. For example, `gluonts.torch.modules.loss` might have moved, or components like `DistributionOutput` might be directly available under `gluonts.torch.distributions`.
GluonTSDataError: Array 'target' has bad shape - expected X dimensions, got Y
This error indicates that the 'target' time series data provided to a GluonTS model has an incorrect number of dimensions compared to what the model expects (e.g., a univariate model expects a 1-dimensional array, but receives a 2-dimensional array).
fix
Reshape your 'target' data to match the expected dimensionality of the model. For univariate models, ensure the target is a 1D array. For multivariate models, ensure it's a 2D array with `(target_dimensionality, sequence_length)` or as expected by the specific model.
ModuleNotFoundError: No module named 'gluonts.trainer' (or 'from gluonts.trainer import Trainer' fails)
The `Trainer` class in GluonTS is no longer directly available under `gluonts.trainer`. It has been moved to backend-specific submodules to distinguish between MXNet and PyTorch implementations.
fix
Import the `Trainer` from the appropriate backend-specific path, such as `from gluonts.mx.trainer import Trainer` for MXNet models or `from gluonts.torch.trainer import Trainer` (or `lightning.pytorch.Trainer` when using PyTorch Lightning directly as GluonTS estimators leverage it) for PyTorch models. For current GluonTS versions (0.16.2), PyTorch models typically use `lightning.pytorch.Trainer` directly with GluonTS estimators that integrate with PyTorch Lightning.
ModuleNotFoundError: No module named 'gluonts.model.deepar' (or 'from gluonts.model.deepar import DeepAREstimator' fails)
Similar to the `Trainer` class, model estimators like `DeepAREstimator` have been moved to backend-specific subpackages to accommodate both MXNet and PyTorch implementations.
fix
Import `DeepAREstimator` from its correct backend-specific location: `from gluonts.mx.model.deepar import DeepAREstimator` for the MXNet version or `from gluonts.torch.model.deepar import DeepAREstimator` for the PyTorch version.
Upgrade
Version history
0.17.0latest on PyPI · released Jul 31, 2026
Audit
Dependencies
torchrequiredRequired for the recommended PyTorch backend.
pytorch-lightningrequiredRequired for the recommended PyTorch backend, often needs specific version alignment.
mxnetoptionalRequired for the MXNet backend.
rpy2optionalRequired for R-based models. Version capped in 0.16.2.
Agent activity
24 hits · last 30 days
node
20
OpenAI (training)
1
Resources
gluonts — pip install gluonts · libregistry