statsforecast

library2.1.1pypypi✓ verified 24d ago

StatsForecast is a Python library providing a lightning-fast suite of statistical and econometric models for time series forecasting. It offers highly optimized implementations of models like ARIMA, ETS, CES, and Theta, designed for speed and scalability to forecast millions of series efficiently. The library is currently at version 2.0.3 and maintains an active release cadence with frequent updates and performance enhancements.

ai-ml data

pip install statsforecast

github ↗package ↗docs ↗

INSTALL

IMPORT

SIG · STATSFORECAST

statsforecast

ai-mlpythonv2.1.1

Install

18.9s avg

Import

1994ms

Disk

567MB

Pass rate

5/ 10

Env Coverage5 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v2.1.1 · 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

py 3.10–3.95 runs

build_error

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 18.9s · import 1.994s · 524MB

567MB installed

● package 567MB

Code

Verified usage

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

StatsForecast

✓ from statsforecast import StatsForecast

AutoARIMA

✓ from statsforecast.models import AutoARIMA

AirPassengersDF

✓ from statsforecast.utils import AirPassengersDF

✗ from statsforecast.core import AirPassengersDF

AirPassengersDF is a utility dataset moved to `statsforecast.utils`.

This quickstart demonstrates how to use StatsForecast to fit an AutoARIMA model to the classic AirPassengers dataset and generate future predictions with confidence intervals. The input DataFrame must be in a 'long' format with 'unique_id', 'ds' (datestamp), and 'y' (target) columns.

import pandas as pd from statsforecast import StatsForecast from statsforecast.models import AutoARIMA from statsforecast.utils import AirPassengersDF # Load example data (AirPassengers dataset) df = AirPassengersDF # Instantiate StatsForecast with models and frequency # For monthly data, 'M' or 'ME' (MonthEnd) is common sf = StatsForecast( models=[AutoARIMA(season_length=12)], freq='M', n_jobs=-1 # Use all available cores for parallel processing ) # Fit the models sf.fit(df) # Make predictions for the next 12 steps (horizon=12) # and calculate 95% prediction intervals forecast_df = sf.predict(h=12, level=[95]) print(forecast_df.head())

statsforecast --version

Debug

Known issues

breakingThe default values for `allowmean` and `allowdrift` in `AutoARIMA` changed from `False` to `True` in `v2.0.0`. This can alter the behavior and results of your `AutoARIMA` forecasts if you were relying on the previous defaults.

fix

Explicitly set `allowmean=False` and/or `allowdrift=False` in `AutoARIMA` constructor if you need the old behavior, or review your models to account for the new defaults.

affects: >=2.0.0

breakingThe `df` argument has been removed from the `StatsForecast` class constructor as of `v2.0.3`. Instead, the DataFrame should be passed directly to the `fit`, `forecast`, or `cross_validation` methods.

fix

Remove the `df` argument from the `StatsForecast()` constructor. Pass your DataFrame directly to methods like `sf.fit(df)` or `sf.forecast(df=df, h=...)`.

affects: >=2.0.3

deprecatedPandas frequency alias 'H' (for hourly data) is deprecated and will be removed in a future version. Use 'h' instead.

fix

Replace `freq='H'` with `freq='h'` when defining the frequency in `StatsForecast` or other pandas-related operations.

affects: >=2.0.2

breakingVersion 2.0.0 included a general breaking change to 'remove deprecated behavior' as part of refactoring. While specific impacts vary, it signals that code using previously deprecated features will likely break.

fix

Consult the official release notes for v2.0.0 and update code using features that were marked as deprecated in earlier versions.

affects: >=2.0.0

Errors

Common errors & fixes

ValueError: df must contain unique_id, ds, y columns

The input DataFrame passed to StatsForecast or its models lacks one or more of the mandatory columns: 'unique_id' (series identifier), 'ds' (datetime), or 'y' (target variable).

fix

Rename your DataFrame columns to 'unique_id', 'ds', and 'y' as required by the library, ensuring 'ds' is a datetime type and 'y' is numeric.
Example: `df.rename(columns={'series_id': 'unique_id', 'timestamp': 'ds', 'sales': 'y'}, inplace=True)`

ImportError: cannot import name 'ARIMA' from 'statsforecast'

Statistical models like ARIMA, ETS, Theta, etc., are not directly available under the top-level `statsforecast` module but are located within the `statsforecast.models` submodule.

fix

Import the models from `statsforecast.models` instead of `statsforecast`.
Example: `from statsforecast.models import ARIMA`

ModuleNotFoundError: No module named 'statsforecast.core'

In older versions of `statsforecast`, the main `StatsForecast` class was located in `statsforecast.core`. In recent versions (including 2.0.3), it has been moved directly under the top-level `statsforecast` module.

fix

Update the import statement to get `StatsForecast` directly from the top-level package.
Example: `from statsforecast import StatsForecast`

RuntimeError: Cannot obtain the number of cores available in the system.

StatsForecast uses parallel processing (via `n_jobs`). This error can occur if the library struggles to determine the number of available CPU cores or if there are issues initializing the parallel backend, especially in restrictive environments like some Docker containers.

fix

Explicitly set `n_jobs=1` in the `StatsForecast` constructor to disable parallel processing, or `n_jobs=-1` to instruct it to use all detected cores if the issue is with detection.
Example: `sf = StatsForecast(models=[ARIMA(season_length=1)], freq='D', n_jobs=1)`

ValueError: freq must be a valid pandas frequency string

The `freq` argument in the `StatsForecast` constructor must be a recognized Pandas frequency string (e.g., 'D' for daily, 'H' for hourly, 'M' for monthly) to correctly handle time series indexing.

fix

Use a valid Pandas frequency string for the `freq` parameter. Common values include 'D', 'H', 'M', 'W', 'Q', 'Y'.
Example: `sf = StatsForecast(models=[ARIMA(season_length=7)], freq='D')`

Upgrade

Version history

2.1.1latest on PyPI · released Jul 16, 2026

Audit

Dependencies

pythonrequiredRequires Python 3.9 or higher.

statsmodelsrequiredPinned in v2.0.2 for compatibility, likely a core dependency for some models.

scipyrequiredPinned in v2.0.2 for compatibility, likely a core dependency for some models.

Agent activity

15 hits · last 30 days

node

OpenAI (training)

Resources

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

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

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