Install & Compatibility
Where this runs
tested against v0.2.16 · 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.95 runs
installs and imports cleanly · install 0.0s · import 0.962s · 170.5MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 8.7s · import 0.926s · 163MB
176MB installed
● package 176MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
fill_gaps
✓ from utilsforecast.preprocessing import fill_gaps
evaluate
✓ from utilsforecast.evaluation import evaluate
mape
✓ from utilsforecast.losses import mape
generate_series
✓ from utilsforecast.data import generate_series
plot_series
✓ from utilsforecast.plotting import plot_series
This quickstart demonstrates how to generate synthetic time series data, fill in artificial gaps using `fill_gaps`, and then evaluate simple dummy forecasts using common metrics like MAPE and MSE with `evaluate`.
import pandas as pd
import numpy as np
from utilsforecast.data import generate_series
from utilsforecast.preprocessing import fill_gaps
from utilsforecast.evaluation import evaluate
from utilsforecast.losses import mape, mse
from functools import partial
# 1. Generate synthetic data with some missing values
series = generate_series(n_series=3, max_length=50, equal_ends=True, seed=42)
# Introduce some gaps for demonstration
mis_idx = np.random.choice(series.index, size=int(len(series) * 0.1), replace=False)
series_with_gaps = series.drop(mis_idx)
# 2. Fill missing values
filled_series = fill_gaps(series_with_gaps, freq='D')
print("Original series head (with gaps if any):")
print(series_with_gaps.head())
print("\nFilled series head:")
print(filled_series.head())
# 3. Prepare data for evaluation (example with dummy models)
# Assume 'y_true' is the actual target and 'model1', 'model2' are predictions
# For demonstration, we'll create a dummy 'y' and then 'predictions'
filled_series['y_true'] = filled_series['y']
filled_series['model1'] = filled_series['y_true'] * np.random.uniform(0.9, 1.1, len(filled_series))
filled_series['model2'] = filled_series['y_true'] * np.random.uniform(0.8, 1.2, len(filled_series))
# Split into train and validation (simplified for quickstart)
horizon = 7
valid_df = filled_series.groupby('unique_id').tail(horizon).copy()
train_df = filled_series.drop(valid_df.index).copy()
# Ensure target column for evaluation matches original 'y'
valid_df['y'] = valid_df['y_true']
train_df['y'] = train_df['y_true']
# 4. Evaluate dummy models
# Mase requires a training set to compute the scaling factor
dummy_mase = partial(mse, seasonality=1)
metrics_df = evaluate(valid_df, metrics=[mape, dummy_mase], train_df=train_df)
print("\nEvaluation Results:")
print(metrics_df.head())
Errors
Common errors & fixes
ImportError: cannot import name 'mae' from 'utilsforecast.losses'
You are trying to import a specific loss function directly from the `utilsforecast.losses` module, which instead contains backend-specific submodules like `numpy` or `torch`, or the metric might be in `utilsforecast.metrics`.
fixImport `mae` from `utilsforecast.metrics` for evaluation metrics or `utilsforecast.losses.numpy` (or `torch`) for specific loss functions, e.g., `from utilsforecast.metrics import mae` or `from utilsforecast.losses.numpy import mae`.
KeyError: "['unique_id', 'ds', 'y']"
Utilsforecast functions expect input DataFrames to have specific column names: `unique_id` for series identifiers, `ds` for timestamps, and `y` for target values, and these columns were not found.
fixRename your DataFrame columns to `unique_id`, `ds`, and `y` before passing them to utilsforecast functions, e.g., `df = df.rename(columns={'series_id': 'unique_id', 'timestamp_col': 'ds', 'target_value': 'y'})`. AttributeError: 'DataFrame' object has no attribute 'group_by_cols'
You are attempting to call `group_by_cols` as a method on a Pandas DataFrame, but it is a standalone function imported from `utilsforecast.data`.
fixImport `group_by_cols` from `utilsforecast.data` and pass your DataFrame as an argument, e.g., `from utilsforecast.data import group_by_cols; grouped_df = group_by_cols(df, ['unique_id'])`.
ValueError: The 'ds' column must be a datetime object or a string that can be parsed as a datetime.
The 'ds' (datestamp) column in your DataFrame is not of a datetime type and cannot be automatically parsed into a valid datetime format by utilsforecast functions.
fixConvert the 'ds' column to a datetime format using Pandas, e.g., `df['ds'] = pd.to_datetime(df['ds'])` before using the DataFrame with utilsforecast functions.
Upgrade
Version history
0.2.16latest on PyPI · released Apr 27, 2026
Audit
Dependencies
pythonrequiredRequires Python 3.9 or newer.
pandasrequiredCore data structures and time series operations.
numpyrequiredNumerical operations, often used internally.