Kats: a one-stop time series toolkit that has barely moved since 2022

Everything starts from a TimeSeriesData object

The design decision that makes Kats pleasant to use is that all three major task families take the same input type. A pandas DataFrame gets wrapped once, and from there it can be forecast, scanned for change points, or turned into a feature vector. That is a smaller claim than a full time series platform, but it is the one the codebase actually delivers, and it removes the per-library dataframe conventions that usually dominate a time series project.

The forecasting example is the shortest illustration. A CSV of the classic `air_passengers` data goes into a DataFrame, that DataFrame becomes a `TimeSeriesData`, parameters go into a params class, and the model is constructed from the two:

import pandas as pd

from kats.consts import TimeSeriesData
from kats.models.prophet import ProphetModel, ProphetParams

air_passengers_ts = TimeSeriesData(air_passengers_df)
params = ProphetParams(seasonality_mode='multiplicative') # additive mode gives worse results
m = ProphetModel(air_passengers_ts, params)
m.fit()
fcst = m.predict(steps=30, freq="MS")

The comment on the params line is a small but honest signal about the level of documentation here. It tells you that multiplicative seasonality wins on this dataset without explaining how to work that out for yours. Note also that the frequency is a string passed to predict, which is the pandas offset convention rather than a native Kats concept.

Detection is a constructor and one method call

Change point detection reads the same way, which is the point. The README example builds a synthetic series with a level shift, wraps it, and runs the detector:

import numpy as np
import pandas as pd

from kats.consts import TimeSeriesData
from kats.detectors.cusum_detection import CUSUMDetector

np.random.seed(10)
timeseries = TimeSeriesData(df_increase)
change_points = CUSUMDetector(timeseries).detector()

The method is named `detector()`, not `detect()`, which is worth knowing before you grep the codebase. CUSUM is one of several algorithms rather than the only one, and the presence of a `detectors` package is what lets you swap it without touching data handling.

The feature extraction path is the third leg:

import pandas as pd
from kats.consts import TimeSeriesData
from kats.tsfeatures.tsfeatures import TsFeatures

features = TsFeatures().transform(air_passengers_ts)

`transform()` returning features rather than a model output is what makes this class usable as a preprocessing step in a larger pipeline, and it is also the piece most likely to be reached for first in practice. The README describes Kats as covering detection, forecasting, feature extraction and embedding, multivariate analysis, and that last category is where the package is deepest and where the README is thinnest.

A minimal install flag that trades features for dependencies

Installation is two commands:

pip install --upgrade pip
pip install kats

The interesting part is the escape hatch. An environment variable switches the install into a reduced mode:

MINIMAL_KATS=1 pip install kats

Looking at `setup.py` explains the mechanism precisely. It reads `requirements.txt` into `install_requires`, reads `test_requirements.txt` into `extra_requires`, and then appends the second list only when `MINIMAL_KATS` is not set in the environment. So the full install is not a curated dependency set, it is the base requirements plus everything the test suite needs. The README is direct about the consequence: the minimal version disables many functionalities and causes `import kats` to log warnings.

That is a slightly unusual packaging decision and a useful one to know about. A user with an existing scientific stack, who only wants the feature extractor, can avoid a resolver fight by setting the variable. A user who installs the full package into a clean environment pulls test dependencies into production, which is the trade the flag exists to avoid.

The dependency pins are the real constraint

Reading `requirements.txt` tells you more about who can use this package than the README does. NumPy is pinned to `>=1.21,<1.22` and pandas to `>=1.0.4,<=1.3.5`, which is a mid-2021 pair. `statsmodels==0.12.2` is pinned to a single exact version. `holidays<=0.57` caps a dependency that regularly changes shape.

Those caps are hard bounds, not floors. On a machine that already has pandas 2.x installed, `pip install kats` has to either downgrade pandas or fail, and a failure that arrives as a resolver conflict deep inside a larger install is a bad first experience. This is the single most likely reason a modern reader tries Kats and gives up before reaching the API.

The classifiers in `setup.py` list Python 3.8, 3.9 and 3.12 alongside a development status of `3 - Alpha`, at `version="0.2.0"`. Those two facts sit awkwardly together. The package is old enough that its alpha label describes its release process rather than its feature set, and the Python range is wide enough that some environments will work while others cannot resolve at all. The README points to `setup.py` for details and options, which is the right pointer.

Also worth noting: `numba>=0.55.0` and `lightgbm>=2.3.0` are present, so some parts of the toolkit pull in compiled dependencies that need a working toolchain.

Release history is two tags, and the changelog cuts off

The repository has two releases. `v0.1` on 2021-06-17 is the initial release of the Python package. `v0.2.0` on 2022-03-15 is described as the second major release since June 2021. The citation block in the README pins version 0.2.0 in its BibTeX entry, which is consistent.

The last push was on 2026-09-21, so commits are still landing. What that means in practice is a repository with active work and a stable public surface: no new tagged version, no release notes beyond the two entries, and a README changelog section that starts a version 0.2.0 list and then stops mid-sentence at a forecasting entry about adding gl. Whether there are further changes below that point is not something the README settles.

For a library rather than an application, this split is normal. Nobody depends on a tagged release when the fix they need is three commits ahead on main. For a package whose install is bound by old pins, it also means the pin problem will not improve on its own.

The citation entry itself is worth a glance because it lists roughly three dozen authors across Meta, which is a fair signal of how many teams touched the code before it was released.

Where the documentation actually lives

The README links a homepage at facebookresearch.github.io, a Facebook engineering blog post from June 2021, a tutorials directory in the repository, a contributing guide, and the PyPI project page. That is a reasonably complete set of destinations, and the tutorials directory is the one most likely to be underused, since the README itself only shows three short snippets.

One piece of research sits alongside the package rather than inside it: self-supervised learning for fast and scalable time series hyper-parameter tuning, with a Meta AI blog post, an arXiv paper at 2102.05740, and a citation for an invited talk at the 40th International Symposium on Forecasting. The README describes it as a framework that automatically optimizes hyper-parameters for time series forecasting models at scale, reducing tuning cost across heterogeneous datasets. It is linked, not shipped, so it is worth separating from the library itself when deciding what you are adopting.

The repository tree matches that story. `kats/` holds the package, `tutorials/` holds notebooks, `sphinx/` holds documentation configuration, and there are `setup.py`, `setup.cfg`, `requirements.txt` and `test_requirements.txt` at the root along with `CITATION.cff`. The licence is MIT, which removes one common concern about adopting a Meta research package.

Editorial conclusion

Kats is worth reaching for when you want change point detection and forecast comparison in the same object model, because the detection and forecasting modules share a TimeSeriesData wrapper and a params object per model, which removes a lot of glue code that StatsForecast or Darts would leave you to write. The honest constraint is the dependency set: `numpy>=1.21,<1.22`, `pandas>=1.0.4,<=1.3.5` and `statsmodels==0.12.2` describe an environment from 2021, and the setup file still classifies the package as alpha at version 0.2.0. Read `setup.py` before you install into an existing environment, and check the tutorials directory, which is where the richer multivariate and embedding examples live.

Frequently asked questions

Official sources

1. facebookresearch/Kats on GitHub
2. Issues
3. License: MIT
4. README
5. Releases