Install & Compatibility
Where this runs
tested against v1.1.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
muslpy 3.10–3.925 runs
build_error
glibcpy 3.10–3.925 runs
installs and imports cleanly · install 33.6s · import 4.310s · 606MB
608MB installed
● package 608MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
MLForecast
✓ from mlforecast import MLForecast
LGBMRegressor
✓ import lightgbm as lgb
models = [lgb.LGBMRegressor()]
MLForecast works with any scikit-learn compatible regressor, e.g., LightGBM, XGBoost.
ExpandingMean
✓ from mlforecast.lag_transforms import ExpandingMean
Differences
✓ from mlforecast.target_transforms import Differences
This quickstart demonstrates how to set up `mlforecast` for a simple time series prediction task. It generates sample daily series data, defines a Linear Regression model with a lag feature (a rolling mean of the target from the previous day), adds date-based features, fits the model, and generates forecasts.
import pandas as pd
from sklearn.linear_model import LinearRegression
from mlforecast import MLForecast
from mlforecast.lag_transforms import RollingMean
from mlforecast.utils import generate_daily_series
# 1. Generate sample time series data
# Data must be in long format with 'unique_id', 'ds', 'y'
df = generate_daily_series(
n_series=5, max_length=100, n_static_features=0, with_trend=True
)
df['ds'] = pd.to_datetime(df['ds'])
# 2. Define models and features
models = [LinearRegression()]
lags = [7]
lag_transforms = {
1: [RollingMean(window_size=7)]
}
date_features = ['dayofweek', 'month']
# 3. Instantiate MLForecast
# freq='D' for daily data; use 'W', 'M', etc. or integer for integer timestamps
forecast_model = MLForecast(
models=models,
freq='D',
lags=lags,
lag_transforms=lag_transforms,
date_features=date_features,
)
# 4. Fit the model
forecast_model.fit(df)
# 5. Make predictions for the next 7 days
h = 7
predictions = forecast_model.predict(h=h)
print(predictions.head())
mlforecast --version
Debug
Known issues
breakingVersion 1.0.0 removed `window_ops` and `numba` as direct dependencies, potentially requiring code changes if these were used explicitly or if custom `window_ops` implementations were relied upon.fixReview your code for direct usage of `window_ops` or `numba` from `mlforecast` and refactor. `mlforecast` now handles efficient feature engineering internally.
affects: >=1.0.0
breakingIn version 0.15.0, the `fit` method's `dropna` parameter's default behavior changed. If `dropna=False` was passed, rows with null targets are now dropped, which was not the case in previous versions.fixEnsure your input data (`df`) passed to `fit` and `preprocess` does not contain `NaN` values in the target column (`y`), especially if you were relying on previous `dropna=False` behavior, as transformations can propagate `NaN`s.
affects: >=0.15.0
gotchaInput dataframes *must* be in a 'long' format with specific column names: `unique_id` (series identifier), `ds` (datestamp/timestamp), and `y` (target value). Deviating from this format will cause errors unless `id_col`, `time_col`, `target_col` are explicitly passed to `MLForecast` methods.fixRename your DataFrame columns to `unique_id`, `ds`, `y` or explicitly pass `id_col`, `time_col`, `target_col` arguments to `MLForecast.fit()` and `MLForecast.predict()` methods.
affects: All versions
gotchaPrediction intervals are not supported when using transfer learning with `MLForecast`. Attempting to combine these functionalities will result in a `ValueError`.fixIf prediction intervals are required, avoid using transfer learning techniques with `MLForecast`. Consider alternative methods for uncertainty quantification in transfer learning scenarios or separate the tasks.
affects: All versions with transfer learning capability
gotchaWhen using distributed Dask DataFrames, if you have more partitions than Dask workers, it's recommended to set `num_threads=1` in `MLForecast` to prevent nested parallelism and potential performance issues or deadlocks.fixExplicitly set `num_threads=1` in the `MLForecast` or `DistributedMLForecast` constructor when working with Dask DataFrames where `df.npartitions > client.n_workers`.
affects: All versions with Dask distributed support
Errors
Common errors & fixes
ImportError: cannot import name '_get_model_name' from 'mlforecast.core'
This error occurs when attempting to import '_get_model_name' from 'mlforecast.core', which is not available in the specified version.
fixEnsure you are using a compatible version of mlforecast that includes '_get_model_name', or update your code to align with the current API.
ModuleNotFoundError: No module named 'mlforecast._modidx'
This error indicates that the module 'mlforecast._modidx' is missing, possibly due to an incomplete or incorrect installation.
fixReinstall mlforecast using 'pip install --force-reinstall mlforecast' to ensure all modules are properly installed.
ValueError: Found missing inputs in X_df. It should have one row per id and time for the complete forecasting horizon. You can get the expected structure by running MLForecast.make_future_dataframe(h) or get the missing combinatins in your current X_df by running MLForecast.get_missing_future(h, X_df).
This error occurs when the `X_df` provided to the `predict` method does not contain all the required future dates and unique IDs for the specified forecasting horizon, especially when using exogenous features.
fixEnsure your `X_df` for prediction is a complete dataframe with an entry for each unique ID and each timestamp within the forecasting horizon, typically by using `MLForecast.make_future_dataframe(h)` or `MLForecast.get_missing_future(h, X_df)` to generate the correct structure.
ValueError: <col_name> is declared as a static feature but its values change over time. Please set the static_features argument to indicate which features are static. If all of your features are dynamic please set static_features=[] .
This error means that a column specified in the `static_features` argument in `MLForecast.fit()` has varying values across different time steps for a given unique ID, contradicting its declaration as a static feature.
fixReview your data and either ensure the feature is truly static, remove it from `static_features` if it's dynamic, or explicitly set `static_features=[]` if all your features change over time.
ModuleNotFoundError: No module named 'mlforecast.feature_engineering' (or 'mlforecast.auto')
This error indicates that the specific submodule being imported, such as `feature_engineering` or `auto`, either does not exist in the installed version of `mlforecast` or its location has changed due to library updates.
fixCheck the official `mlforecast` documentation for the correct import paths for your installed version, or upgrade `mlforecast` to the latest version (`pip install -U mlforecast`) as module structures can evolve between releases. The `auto` module, for example, was added in version 0.12.
Upgrade
Version history
1.1.0latest on PyPI · released Jul 10, 2026
Audit
Dependencies
pandasrequiredPrimary DataFrame format for local operations and examples.
scikit-learnrequiredCommon base for many machine learning models used with MLForecast.
polarsoptionalAlternative high-performance DataFrame backend.
daskoptionalDistributed computing backend.
rayoptionalDistributed computing backend.
pysparkoptionalDistributed computing backend.
fsspecoptionalRequired for saving artifacts to remote storages (e.g., S3, GCS).
s3fsoptionalSpecific fsspec implementation for S3 storage, included in `aws` extra.