{"id":7450,"library":"neuralforecast","title":"NeuralForecast: Deep Learning for Time Series Forecasting","description":"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.","status":"active","version":"3.1.7","language":"en","source_language":"en","source_url":"https://github.com/Nixtla/neuralforecast/","tags":["time series","forecasting","deep learning","pytorch","machine learning","neural networks"],"install":[{"cmd":"pip install neuralforecast","lang":"bash","label":"PyPI"},{"cmd":"conda install -c conda-forge neuralforecast","lang":"bash","label":"Conda-Forge"}],"dependencies":[{"reason":"Core deep learning framework dependency.","package":"torch"},{"reason":"Core deep learning framework dependency.","package":"pytorch-lightning"},{"reason":"Required for data handling (DataFrames).","package":"pandas"},{"reason":"Runtime dependency added in v3.1.7.","package":"scipy"},{"reason":"Dependency for plotting and utilities.","package":"utilsforecast"},{"reason":"Used in examples for loading benchmark datasets.","package":"datasetsforecast","optional":true},{"reason":"Optional for distributed automatic hyperparameter tuning with Auto models.","package":"ray","optional":true},{"reason":"Optional for automatic hyperparameter tuning with Auto models.","package":"optuna","optional":true},{"reason":"Optional dependency, typically for distributed environments.","package":"pyspark","optional":true}],"imports":[{"symbol":"NeuralForecast","correct":"from neuralforecast import NeuralForecast"},{"note":"Or other models like NHITS, NBEATS, DeepAR, etc.","symbol":"LSTM","correct":"from neuralforecast.models import LSTM"},{"note":"Utility for loading example data.","symbol":"AirPassengersDF","correct":"from neuralforecast.utils import AirPassengersDF"},{"note":"Or other PyTorch-based loss functions.","symbol":"MQLoss","correct":"from neuralforecast.losses.pytorch import MQLoss"},{"note":"For automated hyperparameter tuning variants of models.","symbol":"AutoNHITS","correct":"from neuralforecast.auto import AutoNHITS"}],"quickstart":{"code":"import pandas as pd\nfrom neuralforecast import NeuralForecast\nfrom neuralforecast.models import NBEATS\nfrom neuralforecast.utils import AirPassengersDF\n\n# 1. Load data\nY_df = AirPassengersDF # Example dataset with 'unique_id', 'ds', 'y' columns\n\n# 2. Define forecasting horizon\nhorizon = 12\n\n# 3. Instantiate and fit model\nnf = NeuralForecast(\n    models=[NBEATS(input_size=2 * horizon, h=horizon, max_steps=500)],\n    freq='ME' # Monthly End frequency\n)\nnf.fit(df=Y_df)\n\n# 4. Make predictions\nY_hat_df = nf.predict()\n\nprint(Y_hat_df.head())","lang":"python","description":"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."},"warnings":[{"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.","message":"NeuralForecast 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.","severity":"breaking","affected_versions":">=3.0.0"},{"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.","message":"The 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Replace `max_epochs` with `max_steps` when defining your models to ensure future compatibility and fine-grained control over training.","message":"The `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.","severity":"deprecated","affected_versions":"v1.6.1 onwards, with explicit deprecation warnings in newer versions (e.g., v3.x)"},{"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.","message":"NeuralForecast 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`.","severity":"gotcha","affected_versions":"All versions, particularly around major `pytorch` or `pytorch-lightning` releases"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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`).","cause":"The input pandas DataFrame is missing one or more of the required columns: `unique_id`, `ds`, or `y`.","error":"KeyError: \"['unique_id', 'ds', 'y'] not in index\""},{"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.","cause":"Attempting to load a pre-v3.0.0 saved recurrent model checkpoint (e.g., LSTM, GRU) into NeuralForecast v3.0.0 or later.","error":"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."},{"fix":"Replace `max_epochs` with `max_steps` when initializing your NeuralForecast models (e.g., `NBEATS(max_steps=500)` instead of `NBEATS(max_epochs=10)`).","cause":"You are still using the `max_epochs` parameter in your model configuration, which is being phased out.","error":"FutureWarning: `max_epochs` is deprecated as of v1.7.0 and will be removed in a future release. Please use `max_steps` instead."},{"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`).","cause":"Incompatibility between the installed versions of `neuralforecast`, `torch`, and/or `pytorch-lightning`.","error":"TypeError: 'Trainer' object has no attribute 'callbacks' or other PyTorch/Lightning related API incompatibility errors."}]}