tslearn: time series classification, clustering and regression behind a scikit-learn API
The machine learning toolkit for time series analysis in Python
At a glance
- What is it?
- tslearn packages dynamic time warping distance computations and the estimators that use them into a scikit-learn compatible Python library. Its 3D array convention and the cost of elastic distances are the two things that decide whether it fits your project.
- Who is it for?
- Adopt tslearn if your series are short, your dataset is small to medium, and you want k-NN, k-Shape or k-means with DTW to sit inside scikit-learn pipelines and GridSearchCV without writing your own distance code. Do not adopt it if you need forecasting, streaming inference, or sub-second training on tens of thousands of long series; elastic distances will not get you there.
- Can I use it commercially?
- Yes. BSD-2-Clause is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 3 days ago.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The gap tslearn fills: elastic distances inside a scikit-learn estimator
Euclidean distance between two time series compares point i to point i. That fails when one series is a shifted or slightly stretched version of the other, which is the normal case for sensor traces, motion capture and ECG. Dynamic time warping (DTW) aligns the two series first and then measures the residual cost, so a lagged copy of a signal scores as similar. tslearn takes that idea and wraps it in estimators that look like scikit-learn estimators. The README states plainly that models in tslearn follow the same API as scikit-learn and are fully compatible with it, so hyper-parameter tuning and pipelines work. The intended user is an engineer or researcher who already knows scikit-learn and wants DTW-backed classification, clustering or regression without hand-rolling a distance matrix and a custom cross-validation loop. The package topics list dtw, dynamic-time-warping, time-series-classification and time-series-clustering, which is an accurate summary of the centre of gravity.
The 3D array convention and what happens to unequal series
Everything in tslearn starts from one data structure: a 3D numpy array with shape (n_ts, max_sz, d), meaning number of series, number of measurements per series, number of dimensions. The README's first example builds one with to_time_series_dataset, passing three lists of length 4, 4 and 5. The library also states that it supports variable-length time series. Those two facts interact in a way worth understanding before you write code. The printed output of TimeSeriesScalerMinMax in the README shows nan in the trailing slot of the two shorter series: the array is padded to max_sz, and the scaler leaves the padding untouched. So the padding is real and visible in your array, and it is the estimators, not the array itself, that know to ignore it. If you slice, reshape or feed that array to a non-tslearn function, you can silently carry nan values into a computation. The utility functions in tslearn.utils and the conversion helpers documented under integration_other_software exist to keep you inside this convention. This is the single most common place to get a wrong result rather than an exception.
Installation and the pipeline from raw lists to predictions
The README gives three install paths: python -m pip install tslearn from PyPI, conda install -c conda-forge tslearn, or python -m pip install https://github.com/tslearn-team/tslearn/archive/main.zip to install from the main branch. Python 3.10 or later is required according to the badge. The documented workflow has four steps. Format the data with to_time_series_dataset, or load a UCR dataset through tslearn.datasets, or generate synthetic data with the generators module. Preprocess with TimeSeriesScalerMinMax from tslearn.preprocessing, or resample with TimeSeriesResampler, or apply a piecewise transform from tslearn.piecewise. Train an estimator, for example KNeighborsTimeSeriesClassifier(n_neighbors=1) from tslearn.neighbors, using fit and predict exactly as in scikit-learn. Then run further analyses: barycenters from tslearn.barycenters, or distances from tslearn.metrics. The README example fits and predicts on the same three-series array and returns [0 1 1]. That is a demonstration of the API shape, not a result to read anything into. The resampling and piecewise steps are described in the README as ways to speed up training, which tells you the maintainers expect training time to be a concern.
Where tslearn stops being the right tool
Three limits follow from the design. First, cost. DTW is quadratic in series length per pair, and k-NN classification needs distances to the training set at prediction time. The README itself points to resampling and piecewise transforms as ways to speed up training, so the library does not pretend the cost is small. On long series or large training sets, k-NN with DTW becomes the bottleneck, and no amount of pipeline plumbing fixes that. Second, scope. The README lists classification, clustering and regression as the supported tasks. Forecasting is not among them, and the features table covers data, processing, clustering and classification. If your problem is next-step prediction rather than labelling or grouping whole series, tslearn is the wrong library, not a weak one. Third, the 3D array is a hard interface. Anything outside it needs conversion first, and the nan padding means a careless handoff to plain numpy or scikit-learn code produces wrong numbers quietly. A library that fails loudly is easier to live with than one that fails with a nan.
tslearn compared with sktime, and why the difference matters
sktime is the obvious alternative and it is a genuinely different design, not a drop-in swap. sktime organises around a unified forecasting, classification and regression interface with its own time series data containers and a large catalogue of algorithm families, including reduction approaches that turn a series problem into a tabular one. tslearn organises around numpy arrays and elastic distances, with DTW, barycenters and the estimators that consume them as the core. The practical consequence: if your task is forecasting, sktime is in scope and tslearn is not. If your task is clustering series with DTW or k-Shape, or k-NN classification where the alignment matters, tslearn's distance-first design is closer to the problem. The other difference is the data model. tslearn's (n_ts, max_sz, d) array with explicit nan padding is simple to reason about and easy to corrupt; sktime's containers are more structured and more to learn. The README points to a page on converting from other popular time series toolkits, so moving between the two is anticipated rather than treated as an edge case.
Maintenance, releases and the BSD-2-Clause licence
The repository is not archived and the most recent push recorded is 2026-09-10. Releases in the supplied material are v0.9.0 (2026-06-30), v0.8.1 (2026-03-13) and v0.8.0 (2026-02-19), which is a steady cadence of roughly one minor release every few months with patch releases between. The version numbers are still below 1.0, so the maintainers reserve the right to change APIs between minor versions, and you should read the release notes before upgrading rather than assuming v0.8 to v0.9 is a no-op. The licence is BSD-2-Clause: permissive, short, and it does not impose copyleft obligations on your own code. That is a statement about the licence text, not legal advice; if you are redistributing tslearn inside a product, have your own counsel read the file. The dependency situation is the practical upgrade cost. The README notes that required dependencies must be installed for the installation to succeed and defers to the documentation for the detailed guide, so pinning tslearn without pinning numpy and scipy alongside it is how you get a broken environment after an unrelated upgrade.
What to verify before you build on it
Run three checks on your own data before you commit. One: build your array with to_time_series_dataset and confirm the shape is (n_ts, max_sz, d) and that unequal lengths show up as the padded nan pattern the README prints, not as an exception or a silently truncated series. Two: fit KNeighborsTimeSeriesClassifier with n_neighbors=1 on a small labelled slice and time it, then repeat after TimeSeriesResampler or a piecewise transform from tslearn.piecewise, and see whether the speedup the README promises for resampling actually materialises at your series lengths. Three: confirm the task is classification, clustering or regression, because if it is forecasting, stop here. If all three pass, tslearn gives you DTW-backed estimators that plug into GridSearchCV and sklearn pipelines, which is the specific thing it was built to give you.
Editorial conclusion
Adopt tslearn if your series are short, your dataset is small to medium, and you want k-NN, k-Shape or k-means with DTW to sit inside scikit-learn pipelines and GridSearchCV without writing your own distance code. Do not adopt it if you need forecasting, streaming inference, or sub-second training on tens of thousands of long series; elastic distances will not get you there. Before committing, verify two things on your own data: that to_time_series_dataset plus TimeSeriesScalerMinMax produces the (n_ts, max_sz, d) array your estimator expects, and that TimeSeriesResampler or a piecewise transform brings training time within budget. Both are documented, both are cheap to test, and together they decide the adoption.
Community notes