Skip to main content
v2026.11,986 entries · CC-BY 4.0

pmdarima: auto_arima in Python, Install, Parameters and Output

Install pmdarima, fit auto_arima on a seasonal series, read the summary and holdout-test forecasts, and note what to report in methods.

Written and maintained by CASRAI Editorial Board

Published

On this page

pmdarima is a Python library that brings the automatic ARIMA model search of R’s forecast::auto.arima to Python. Its main function, auto_arima, tests for stationarity, searches over non-seasonal and seasonal ARIMA orders and returns the model that minimises an information criterion. The current release on PyPI is 2.1.1 (pmdarima requires Python 3.10 or later), and the project documentation describes it as 100% Python and Cython that does not use any R code. This page covers installation, a worked example, the parameters that change results, how to read the output and what to report when you use it in research.

What pmdarima is used for in research

Researchers use pmdarima to model and forecast a single time series, such as a monthly count, a sensor reading or a registry metric, without hand-selecting every ARIMA order. The package wraps statsmodels’ SARIMAX estimation in a scikit-learn-like API: you call fit on a series, then predict for future periods. The documentation lists the ARIMA estimator’s methods as fit, predict, update, summary, aic and bic, and exposes the underlying statsmodels results object as arima_res_.

The automatic search does not remove the modelling decisions; it moves them into parameter choices that you must be able to state. The Box-Jenkins steps (decide on differencing, identify orders, estimate, check residuals) are covered in ARIMA models for research time series. In pmdarima, differencing is chosen by a unit-root test, order selection by an information criterion, and residual checking stays with you. Readers who work in R will recognise the same idea in forecast in R.

Install or access

Install from PyPI with pip install pmdarima. The setup page of the project documentation lists minimum dependencies: NumPy 1.17.3 or later, SciPy 1.3.2, scikit-learn 0.22, pandas 0.19 and statsmodels 0.11. To confirm the install works, run:

from pmdarima.arima import auto_arima

If that raises an ImportError, the setup page advises updating NumPy and reinstalling, noting that outdated NumPy versions have been observed to break the pmdarima build. For conda, the documentation gives these commands; the conda package is maintained by conda-forge, not by the pmdarima project:

conda config --add channels conda-forge
conda config --set channel_priority strict
conda install pmdarima

Building from source needs a C compiler (gcc, or MinGW on Windows) because the package uses Cython. To record the environment for a methods section, pm.show_versions() prints the installed versions of pmdarima and its dependencies.

Step-by-step: fit a seasonal model and forecast

The documentation quickstart uses the bundled wineind dataset (monthly data, so the seasonal period is 12). The numbered steps below follow it.

  1. Import and load the series.
    import numpy as np
    import pmdarima as pm
    from pmdarima.datasets import load_wineind
    wineind = load_wineind().astype(np.float64)

    The input y must be one-dimensional with no NaN or infinite values, so clean or impute missing values before fitting.

  2. Run the search.
    stepwise_fit = pm.auto_arima(wineind, start_p=1, start_q=1,
                                 max_p=3, max_q=3, m=12,
                                 seasonal=True, d=1, D=1, trace=True,
                                 error_action='ignore',
                                 suppress_warnings=True,
                                 stepwise=True)

    Here m=12 sets twelve periods per season, d=1 and D=1 fix the non-seasonal and seasonal differencing, and trace=True prints each candidate model as it is fitted.

  3. Inspect the chosen model.
    stepwise_fit.summary()

    This prints the SARIMAX results table described in the next section.

  4. Forecast. Call predict with the number of periods ahead. The ARIMA method signature is predict(n_periods, X, return_conf_int, alpha), so stepwise_fit.predict(n_periods=12, return_conf_int=True) returns forecasts together with confidence intervals. If you fitted with exogenous regressors X, you must supply X again when forecasting.

Letting the search choose differencing

If you leave d as None, auto_arima uses a unit-root test to decide the differencing order; the default test is KPSS, and for seasonal models the seasonal test defaults to OCSB. Set stationary=True only if you have already established that the series is stationary, since it fixes d at zero. The documentation’s stock-price use case instead estimates d itself with pmdarima.arima.ndiffs under both the KPSS and ADF tests (alpha=0.05, max_d=6), takes the larger result and passes it as d. Reporting which approach you used is part of making the analysis reproducible.

Holdout evaluation for research use

A single in-sample AIC does not tell you how well the model forecasts. The use-case page splits the series with pmdarima.model_selection.train_test_split, keeping 80% of rows for training (train_len = int(df.shape[0]*0.8)), fits auto_arima on the training part, then forecasts one step at a time with model.predict(n_periods=1, return_conf_int=True). After each forecast it passes the observed value to model.update(new_ob), which the page describes as updating the existing model with a small number of maximum-likelihood steps, and it scores the forecasts with smape from pmdarima.metrics. Alternatively, auto_arima can hold out the tail of the series itself: out_of_sample_size is the number of final observations used as validation examples, scored by the metric in scoring (default 'mse') when it is greater than zero.

Output and how to read it

By default auto_arima returns only the best fit; with return_valid_fits=True it returns a list of all valid fits. With trace=True you see one line per candidate model during the search. The summary() call shows a SARIMAX results table with the coefficients, AIC, BIC, and diagnostic tests including Ljung-Box and Jarque-Bera.

  • Order and seasonal order. The selected (p, d, q) and (P, D, Q, m) are what you report. The stock use case reads them from auto.order.
  • AIC and BIC. Lower is better when comparing models fitted to the same series. The search criterion is set by information_criterion, which accepts 'aic' (the default), 'aicc', 'bic', 'hqic' and 'oob'.
  • Ljung-Box. A test for remaining autocorrelation in the residuals; see the Ljung-Box test for interpretation. A significant result suggests the model has not captured the dependence in the series.
  • Jarque-Bera. A test of whether the residuals are consistent with a normal distribution, which matters for the confidence intervals returned by predict.

Because the fitted object wraps statsmodels, arima_res_ gives access to the full statsmodels results if you need residual plots or diagnostics beyond the summary; see the statsmodels API guide for that library’s conventions.

What to report in a methods section

State the pmdarima version (2.1.1 at the time of writing), the search method (stepwise, following the algorithm of Hyndman and Khandakar, 2008, which is what the documentation names for stepwise=True), the information criterion, the unit-root tests, the seasonal period m, any bounds such as max_p and max_q, the selected orders, and the validation scheme and metric. Without these, a reader cannot tell whether a different order would have been chosen under different settings.

Parameters that change the result

The data table below lists the defaults documented for auto_arima in version 2.1.1, with what each controls. A few notes on interaction that the table cannot show:

  • m=1 means non-seasonal data; if seasonal is True and m is 1, seasonal is set to False. Forgetting to set m therefore silently gives a non-seasonal search.
  • stepwise=True is the default search. Setting stepwise=False runs a grid search, which the documentation warns can be slower, especially when seasonal=True; max_order then limits the sum p+q+P+Q, and n_jobs sets how many models fit in parallel (it applies to the grid search only).
  • random=True fits only n_fits models drawn at random, and the documentation states that stepwise must be False for this option to do anything.
  • suppress_warnings=True silences warnings from the underlying ARIMA fits. That keeps logs readable but can hide convergence problems, so inspect the summary of the final model.

Troubleshooting

  • ImportError after install. Update NumPy and reinstall, as the setup page advises.
  • Build errors when installing from source. A compiler is required because of the Cython code (gcc, or MinGW on Windows).
  • Errors about the input series. The documentation requires a one-dimensional array without NaN or infinite values. Check for missing values first.
  • A non-seasonal model when you expected a seasonal one. Check that m is greater than 1.
  • Many candidate models failing. The error_action parameter controls what happens when a candidate cannot be fitted; the examples in the documentation pass error_action='ignore' to move past failed fits. Review trace=True output rather than assuming every candidate was evaluated.
  • Forecasting with regressors. Supply X again in predict if you supplied it when fitting.

Free alternatives

Option Language Relationship to pmdarima
statsmodels (ARIMA, SARIMAX) Python pmdarima’s estimation sits on statsmodels, and arima_res_ is a statsmodels results wrapper. Use statsmodels directly when you want to choose orders yourself. See statsmodels API.
forecast::auto.arima R The function pmdarima’s PyPI summary describes itself as the equivalent of. See forecast in R.

FAQ

What does pmdarima stand for and what is it?

It is the PyPI package name of a Python library for ARIMA modelling whose PyPI summary reads “Python’s forecast::auto.arima equivalent”. Install it with pip install pmdarima and import it as pmdarima.

Does pmdarima use R?

No. The project documentation says it is 100% Python and Cython and does not leverage any R code.

How does auto_arima choose the model?

By default it uses a stepwise search following Hyndman and Khandakar (2008) and returns the model that minimises the chosen information criterion (AIC by default).

Can pmdarima handle seasonality?

Yes: set m to the number of periods per season (for example 12 for monthly data). With m=1 the search is non-seasonal.

How do I update a fitted model with new data?

Call update(y, X, maxiter) on the fitted ARIMA object; the stock use case calls model.update(new_ob) for each new observation.

Sources

Data: pmdarima 2.1.1 auto_arima: documented default parameter values

Default values of selected auto_arima parameters in the pmdarima 2.1.1 documentation, with a short statement of what each parameter controls, compiled from the project's API reference page.

Period covered: 2026.

pmdarima 2.1.1 auto_arima: documented default parameter values
ParameterDocumented defaultWhat it controls
start_p2Starting order of the autoregressive (AR) term for the search
start_q2Starting order of the moving-average (MA) term
max_p5Maximum AR order
max_q5Maximum MA order
max_d2Maximum non-seasonal differencing
max_order5Limit on p+q+P+Q for the non-stepwise search
m1Periods per season (1 = non-seasonal)
seasonalTrueWhether to fit a seasonal ARIMA (set False when m=1)
stationaryFalseIf True, d is set to zero
testkpssUnit-root test used to pick d when d is None
seasonal_testocsbSeasonal unit-root test used when D is None
information_criterionaicCriterion for selecting the best model (aic, aicc, bic, hqic, oob)
stepwiseTrueStepwise search (Hyndman and Khandakar, 2008) instead of grid search
n_jobs1Models fitted in parallel in a grid search
out_of_sample_size0Tail observations held out for validation
scoringmseMetric for out-of-sample scoring

Sources

Compiled by CASRAI from the sources above. Free to reuse under CC BY 4.0 with attribution.

Follow CASRAI

Research-administration guidance, standards updates and independent tool reviews.

Ask CASRAI · free to try

Ask about pmdarima: auto_arima in Python, Install, Parameters and Output

2 free questions a day, no account.

An AI assistant for research: funder rules, compliance, methods and publishing. It links the sources behind its answers and labels answers that come from a web search.

Answers draw on CASRAI's guides and dictionary plus the federal and funder documents we index: Federal Register, Grants.gov, Regulations.gov and UKRI.

Works on this site and inside Claude, Cursor and the AI tools you already use.

Everything CASRAI publishes — this page, the dictionary, the guides and the news — stays open to read, with no account and no card.

Referenced across the research world

University of Cambridge logoColumbia University logoCrossref logoUniversity of Edinburgh logoHarvard University logoUniversity of Oxford logoPrinceton University logoStanford School of Medicine logoUniversity College London logoORCID logoUniversity of Cambridge logoColumbia University logoCrossref logoUniversity of Edinburgh logoHarvard University logoUniversity of Oxford logoPrinceton University logoStanford School of Medicine logoUniversity College London logoORCID logo
  • University of Cambridge logo
  • Columbia University logo
  • Crossref logo
  • University of Edinburgh logo
  • Harvard University logo
  • University of Oxford logo
  • Princeton University logo
  • Stanford School of Medicine logo
  • University College London logo
  • ORCID logo

View CASRAI adoption →