Install & Compatibility
Where this runs
tested against v0.21.2 · 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.940 runs
build_error
glibcpy 3.10–3.940 runs
installs and imports cleanly · install 23.3s · import 9.143s · 779MB
796MB installed
● package 796MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
extract_features
✓ from tsfresh import extract_features
select_features
✓ from tsfresh import select_features
impute
✓ from tsfresh.utilities.dataframe_functions import impute
MinimalFCParameters
✓ from tsfresh.feature_extraction import MinimalFCParameters
EfficientFCParameters
✓ from tsfresh.feature_extraction import EfficientFCParameters
ComprehensiveFCParameters
✓ from tsfresh.feature_extraction import ComprehensiveFCParameters
This quickstart demonstrates how to extract features from a simple pandas DataFrame using `tsfresh`. It creates a dummy time series, defines minimal feature calculation settings, and then extracts features, utilizing parallel processing. The `impute_function` is important for robust handling of missing values.
import pandas as pd
from tsfresh import extract_features
from tsfresh.utilities.dataframe_functions import impute
from tsfresh.feature_extraction import MinimalFCParameters
# Create a sample time series DataFrame
# 'id' identifies different time series
# 'time' is the time index within each series (can be datetime or int)
# 'value' is the measurement
df = pd.DataFrame({
'id': [1, 1, 1, 2, 2, 2, 3, 3, 3],
'time': [1, 2, 3, 1, 2, 3, 1, 2, 3],
'value': [10, 12, 11, 5, 6, 7, 8, 8, 9]
})
# Define feature extraction settings (e.g., Minimal for speed)
settings = MinimalFCParameters()
# Extract features
# impute_function is recommended to handle NaN values gracefully
features = extract_features(df,
column_id='id',
column_sort='time',
impute_function=impute,
default_fc_parameters=settings,
n_jobs=0) # Use all CPU cores for parallelization
print("Extracted Features:")
print(features.head())
Debug
Known issues
breakingtsfresh v0.21.0 dropped support for Python 3.7 and 3.8. v0.19.0 dropped Python 3.6. Ensure your Python environment is 3.9 or newer.fixUpgrade your Python interpreter to version 3.9 or higher.
affects: >=0.19.0
breakingThe `matrixprofile` package became an optional dependency in v0.20.0. If you use features relying on matrix profile without installing it, you will encounter `ModuleNotFoundError`.fixInstall the optional dependency: `pip install tsfresh[matrix_profile]` or `pip install matrixprofile`.
affects: >=0.20.0
gotchaParallelization with `n_jobs > 1` (default `n_jobs=0` uses all cores) requires Dask and Distributed. Without them, you'll receive a `RuntimeError` if parallelization is attempted.fixInstall Dask and Distributed: `pip install tsfresh[dask]` or `pip install dask distributed`. Also, be aware of potential multiprocessing issues in certain environments (e.g., Jupyter notebooks on Windows).
affects: all
gotchaCompatibility issues with `scipy` versions 1.15 and higher were fixed in `tsfresh v0.21.0` by relying on the `pywavelets` package for CWT. Older `tsfresh` versions or environments without `pywavelets` might fail.fixUpgrade to `tsfresh >= 0.21.0` and ensure `pywavelets` is installed (`pip install pywavelets` or `pip install tsfresh[pywavelets]` for newer versions).
affects: <0.21.0 (with scipy >= 1.15)
gotcha`tsfresh v0.20.1` added compatibility with NumPy 1.24 and Pandas 2.0. Using older `tsfresh` versions with newer NumPy/Pandas might lead to unexpected errors or warnings related to API changes.fixUpgrade `tsfresh` to at least `0.20.1` if you are using recent versions of NumPy or Pandas.
affects: <0.20.1 (with numpy >= 1.24 or pandas >= 2.0)
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'matrixprofile'
Attempting to extract features that depend on the `matrixprofile` library (e.g., `matrix_profile`) without having it installed.
fixInstall the optional `matrixprofile` dependency: `pip install tsfresh[matrix_profile]` or `pip install matrixprofile`.
RuntimeError: Please install dask and distributed for parallel processing.
You are trying to use parallel feature extraction (`n_jobs > 1` or `n_jobs=0`) but the Dask and Distributed libraries are not installed.
fixInstall the optional Dask/Distributed dependencies: `pip install tsfresh[dask]` or `pip install dask distributed`.
ValueError: column_id not found in dataframe
The DataFrame passed to `extract_features` does not contain a column with the name specified by `column_id`.
fixEnsure your DataFrame has a column named 'id' (or whatever you pass to `column_id`) and that it correctly identifies individual time series.
TypeError: Cannot convert float NaN to integer
This often occurs when feature calculators expect integer inputs but encounter NaN values in the time series data. While `tsfresh` tries to handle NaNs, some specific cases or older versions might not.
fixEnsure `impute_function=impute` is passed to `extract_features`. Also, consider preprocessing your data to handle NaNs explicitly before passing it to `tsfresh` if the issue persists.
Upgrade
Version history
0.21.2latest on PyPI · released May 31, 2026
Audit
Dependencies
daskoptionalOptional: For distributed parallel feature extraction (n_jobs > 1)
distributedoptionalOptional: For distributed parallel feature extraction (n_jobs > 1)
matrixprofileoptionalOptional: For matrix profile related features
pywaveletsoptionalOptional: For continuous wavelet transform features, especially with scipy >= 1.15