Registry / ai-ml / neuralforecast

neuralforecast

library3.1.9pypypi✓ verified 84d ago

NeuralForecast is an active Python library (current version 3.1.7) providing a comprehensive suite of state-of-the-art deep learning models for time series forecasting. It emphasizes performance, usability, and robustness, offering implementations of various architectures from classic RNNs to modern transformers. The library maintains a frequent release cadence, with several patch releases within major versions addressing features, bug fixes, and documentation improvements.

ai-ml data

pip install neuralforecast

github ↗package ↗docs ↗

INSTALL

IMPORT

SIG · NEURALFORECAST

neuralforecast

ai-mlpythonv3.1.9

Install

—

Import

—

Disk

—

Pass rate

0/ 10

Env Coverage0 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v3.1.9 · 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

✕ timeout

py 3.11

✕ build_error

✕ timeout

py 3.12

✕ build_error

✕ timeout

py 3.13

✕ build_error

3/4 runs

py 3.9

✕ build_error

✕ timeout

Code

Verified usage

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

NeuralForecast

✓ from neuralforecast import NeuralForecast

LSTM

✓ from neuralforecast.models import LSTM

Or other models like NHITS, NBEATS, DeepAR, etc.

AirPassengersDF

✓ from neuralforecast.utils import AirPassengersDF

Utility for loading example data.

MQLoss

✓ from neuralforecast.losses.pytorch import MQLoss

Or other PyTorch-based loss functions.

AutoNHITS

✓ from neuralforecast.auto import AutoNHITS

For automated hyperparameter tuning variants of models.

This quickstart demonstrates how to load a sample dataset, define a NeuralForecast model (NBEATS in this case), fit it to the data, and generate predictions. The input DataFrame must contain 'unique_id', 'ds' (datestamp), and 'y' (target variable) columns. The `freq` parameter is crucial for time series interpretation.

import pandas as pd from neuralforecast import NeuralForecast from neuralforecast.models import NBEATS from neuralforecast.utils import AirPassengersDF # 1. Load data Y_df = AirPassengersDF # Example dataset with 'unique_id', 'ds', 'y' columns # 2. Define forecasting horizon horizon = 12 # 3. Instantiate and fit model nf = NeuralForecast( models=[NBEATS(input_size=2 * horizon, h=horizon, max_steps=500)], freq='ME' # Monthly End frequency ) nf.fit(df=Y_df) # 4. Make predictions Y_hat_df = nf.predict() print(Y_hat_df.head())

Debug

Known issues

breakingNeuralForecast v3.0.0 introduced significant API changes, including unified API, all models inheriting `BaseModel`, recurrent models requiring an `input_size` parameter, and TCN/DRNN becoming window models. Loading recurrent models saved with pre-v3.0.0 versions is not supported.

fix

Review your model implementations and saved checkpoints. Adapt to the new API structure (e.g., `BaseModel` inheritance, `input_size` for recurrent models). Re-train models saved with older versions if necessary.

affects: >=3.0.0

gotchaThe input DataFrame for `NeuralForecast.fit()` and `NeuralForecast.predict()` must be in a 'long' format with specific column names: `unique_id` (series identifier), `ds` (datestamp/temporal index), and `y` (target variable). Missing or incorrectly named columns will cause errors.

fix

Ensure your pandas DataFrame has the columns `['unique_id', 'ds', 'y']`. For single time series, assign a common `unique_id` (e.g., `1`) to all rows. Convert `ds` to datetime objects for proper handling.

affects: All versions

deprecatedThe `max_epochs` parameter for model training is being deprecated in favor of `max_steps`. While it may still work, using `max_steps` is the recommended approach for defining training iterations.

fix

Replace `max_epochs` with `max_steps` when defining your models to ensure future compatibility and fine-grained control over training.

affects: v1.6.1 onwards, with explicit deprecation warnings in newer versions (e.g., v3.x)

gotchaNeuralForecast has shown sensitivity to `pytorch` and `pytorch-lightning` versions. Incompatible versions can lead to runtime errors or unexpected behavior. For example, `neuralforecast >=1.7.2` required `pytorch-lightning >=2.1.0`, and `v3.0.1` specified `2.0.0 <= pytorch <= 2.6.0`.

fix

Always check the `neuralforecast` documentation or release notes for recommended `pytorch` and `pytorch-lightning` versions. If encountering issues, try pinning these dependencies to known compatible ranges.

affects: All versions, particularly around major `pytorch` or `pytorch-lightning` releases

Errors

Common errors & fixes

KeyError: "['unique_id', 'ds', 'y'] not in index"

The input pandas DataFrame is missing one or more of the required columns: `unique_id`, `ds`, or `y`.

fix

Rename your DataFrame columns to `unique_id`, `ds`, `y` or ensure they are present. For a single series, add a `unique_id` column with a constant value (e.g., `df['unique_id'] = 1`).

RuntimeError: Unable to load model. Model architecture from previous versions (pre-v3.0.0) cannot be loaded after the v3.0.0 API unification for recurrent models.

Attempting to load a pre-v3.0.0 saved recurrent model checkpoint (e.g., LSTM, GRU) into NeuralForecast v3.0.0 or later.

fix

Re-train your models using NeuralForecast v3.0.0 or a newer version and save the checkpoints. Pre-v3.0.0 recurrent model checkpoints are incompatible with the new API.

FutureWarning: `max_epochs` is deprecated as of v1.7.0 and will be removed in a future release. Please use `max_steps` instead.

You are still using the `max_epochs` parameter in your model configuration, which is being phased out.

fix

Replace `max_epochs` with `max_steps` when initializing your NeuralForecast models (e.g., `NBEATS(max_steps=500)` instead of `NBEATS(max_epochs=10)`).

TypeError: 'Trainer' object has no attribute 'callbacks' or other PyTorch/Lightning related API incompatibility errors.

Incompatibility between the installed versions of `neuralforecast`, `torch`, and/or `pytorch-lightning`.

fix

Check the `neuralforecast` documentation or GitHub releases for the recommended compatible versions of `torch` and `pytorch-lightning`. Pin these dependencies in your environment (e.g., `pip install torch==2.1.0 pytorch-lightning==2.1.0 neuralforecast==3.1.7`).

Upgrade

Version history

3.1.9latest on PyPI · released May 28, 2026

Audit

Dependencies

torchrequiredCore deep learning framework dependency.

pytorch-lightningrequiredCore deep learning framework dependency.

pandasrequiredRequired for data handling (DataFrames).

scipyrequiredRuntime dependency added in v3.1.7.

utilsforecastrequiredDependency for plotting and utilities.

datasetsforecastoptionalUsed in examples for loading benchmark datasets.

rayoptionalOptional for distributed automatic hyperparameter tuning with Auto models.

optunaoptionalOptional for automatic hyperparameter tuning with Auto models.

pysparkoptionalOptional dependency, typically for distributed environments.

Agent activity

12 hits · last 30 days

node

Resources

githubhttps://github.com/Nixtla/neuralforecast ↗

packagehttps://pypi.org/project/neuralforecast/ ↗

docshttps://nixtlaverse.nixtla.io/neuralforecast/ ↗