Guide · Open source
How to use Time-Series-Library: clone, run and compare models
Updated · written with AI from the project's own documentation and checked against our catalogue data
Time-Series-Library (TSLib) is an open-source Python code base from the THUML group that collects many deep learning models for time series data, such as sensor readings or prices over time. It gives you one shared setup to evaluate these models and to build your own. This guide explains what it is good for, how to get the code, and what you can do with it once it is installed.
Time-Series-Librarythuml/Time-Series-Library · ★ 13k · MIT Install options & downloads Quick start
- 1Check prerequisites. Make sure Python and pip are installed. Docker is optional and only needed if you want the docker deployment mentioned in the README.
- 2Clone the repository. Run the git clone command to download the Time-Series-Library code to your machine.
- 3Install the requirements. Follow the requirements file and setup instructions in the cloned repository's README.
- 4Read the TimesNet tutorial. Open the tutorial notebook in the tutorial folder to see how a model is trained and evaluated.
- 5Run an example script. Pick a task folder under scripts, such as long_term_forecast, and run a script for a model you want to test.
- 6Compare or extend. Run other models on the same task for a fair comparison, or add your own model file in the models folder.
What is TSLib and who is it for?
TSLib is a library for deep learning researchers, especially for deep time series analysis. It provides a neat code base to evaluate advanced deep time series models or to develop your own model. It covers five tasks: long- and short-term forecasting, imputation (filling in missing values), anomaly detection, and classification.
It suits researchers comparing models on common tasks, developers who want reference implementations of models such as TimesNet, iTransformer or PatchTST, students learning deep time series analysis, and teams prototyping a custom model within a shared experiment setup.
Install TSLib by cloning the repository
TSLib uses a clone-and-build approach. Start by cloning the repository with git. You will need Python and pip. The README also mentions a Docker deployment as an optional route, added in a later update to the project.
Once cloned, change into the project folder and follow the setup in the repository's README and requirements files.
- Prerequisites: Python and pip
- Optional: Docker, for the docker deployment mentioned in the README
- Mamba model only: install mamba_ssm with pip first, as the README notes
git clone https://github.com/thuml/Time-Series-Library.gitKnow the five tasks TSLib covers
Every model in the library is organised around the same five tasks, so you can swap models while keeping the experiment setup constant. Pick the task that matches your data before you choose a model.
- Long-term forecasting: predicting far ahead over a series
- Short-term forecasting: predicting the near future
- Imputation: filling in missing values
- Anomaly detection: flagging unusual points in a series
- Classification: assigning a label to a whole series
Choose a model to start with
TSLib includes many models, each stored as a file in the models folder. The README lists reference implementations such as TimesNet, iTransformer, PatchTST, TimeXer, TimeMixer, TSMixer, DLinear, LightTS and ETSformer. The README's TimesNet tutorial is a good first read for beginners.
The README's leaderboard ranks models per task, but the maintainers say many older benchmarks may no longer be meaningful, so treat rankings as a historical snapshot rather than a current verdict.
- models/TimesNet.py, the model used in the README tutorial
- models/iTransformer.py
- models/PatchTST.py
- models/TimeXer.py
Run experiments and compare models
The repository ships example scripts organised by task. For instance, the README points to a long-term forecasting script for ETT data under scripts/long_term_forecast/ETT_script/. A zero-shot forecasting feature and a script for evaluating Large Time Series Models are also mentioned there.
Because every model shares the same codebase, you can run the same task with different models and compare their results on equal terms.
- Keep the dataset and task fixed when comparing models
- Use the example scripts as templates for your own experiments
- Read the TimesNet tutorial notebook in the tutorial folder for a walk-through
Build or test your own model
TSLib is also a place to develop a model. Add your model as a new file alongside the existing ones in the models folder, then run it through the same experiment setup used for the built-in models. The README invites contributions: you can send a paper or code link or raise a pull request, and the maintainers say they will add advanced models to the repo.
What people use it for
- Benchmarking TimesNet against iTransformer or PatchTST on a forecasting dataset
- Filling gaps in a sensor log using the imputation task
- Flagging unusual readings in a series with the anomaly detection task
- Prototyping a custom time series model inside a shared experiment setup
- Learning deep time series analysis from the TimesNet tutorial
Frequently asked questions
Is Time-Series-Library free to use?
TSLib is released under the MIT licence, as stated on the repository page. The MIT licence generally permits use, modification and distribution, but check the licence text for the exact terms before reuse.
How do I install Time-Series-Library?
The README's install step is to clone the repository with git clone https://github.com/thuml/Time-Series-Library.git. You need Python and pip, and Docker is optional for the docker deployment the README mentions.
What do I need to run TSLib?
The stated prerequisites are Python and pip. Docker is optional. Some models, such as Mamba, need an extra package: the README says to install mamba_ssm with pip first.
Can I use TSLib for production forecasting?
The README frames TSLib as a research codebase, so it is not a ready-made production forecasting service. Teams that need a deployed service should look for a tool built for that purpose.
Will TSLib get new features?
The README says the maintainers will not actively add new features in 2026 because of limited bandwidth. The baseline implementations remain correct, according to the README.
How does TSLib compare to Darts, sktime or Autoformer?
Darts and sktime are general time series toolkits, while TSLib focuses on deep learning models for five tasks in one codebase. Autoformer is one of the models that came from the same THUML group and is included in the wider project lineage.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
TSLib suits deep learning researchers, students and developers who want reference implementations and a shared setup for comparing time series models. It is less suitable if you need a ready-made production forecasting service or current state-of-the-art benchmarks, since the maintainers have stopped adding features and say older benchmarks may be out of date.
Install options & downloads