# Uni2TS and Moirai: a PyTorch library for pre-training and running universal time series transformers

> Uni2TS is the Salesforce research library behind the Moirai family of forecasting models. It bundles pre-training, fine-tuning, inference and evaluation in one package, but it is an alpha-stage research codebase pinned to older dependency versions.

**SalesforceAIResearch/uni2ts** — Unified Training of Universal Time Series Forecasting Transformers

- Repository: https://github.com/SalesforceAIResearch/uni2ts
- Stars: 1,603 · Forks: 217
- Language: Jupyter Notebook
- License: Apache-2.0
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/salesforceairesearch-uni2ts

## The problem Uni2TS addresses: one training and inference path across many time series

Most forecasting code is written per dataset. A retail demand series, a sensor stream and a weather series get separate preprocessing, separate model classes and separate evaluation scripts. Uni2TS is built for the opposite arrangement: a single transformer trained across many series and then applied to new ones without retraining. The README describes it as "a unified framework for large-scale pre-training, fine-tuning, inference, and evaluation of Universal Time Series Transformers."

The audience is narrow and specific. This is for researchers and applied ML engineers who already work in PyTorch and want to either reproduce the Moirai results, fine-tune a released checkpoint on their own corpus, or benchmark another model against the same harness. The repository also ships evaluation code for TimesFM, Chronos and VisionTS on the Monash, LSF and PF benchmarks, which tells you the intended use is comparative research rather than a drop-in forecasting service. If you want a library that trains a gradient-boosted model on a CSV and returns a number, this is the wrong layer of the stack.

## How the Moirai pipeline moves from a wide DataFrame to sampled forecast paths

The mechanism visible in the README is a chain of four libraries. pandas holds the input as a wide DataFrame, one column per series. GluonTS wraps it in a PandasDataset and provides the splitting and rolling-window machinery. Uni2TS supplies the model classes. Hugging Face Hub supplies the weights.

The model classes are the part that matters. MoiraiForecast, MoiraiMoEForecast and Moirai2Forecast each take a module loaded from a Hub checkpoint plus a set of shape parameters: prediction_length, context_length, patch_size, num_samples, target_dim, feat_dynamic_real_dim and past_feat_dynamic_real_dim. The patch size controls how the input series is cut into tokens, which is the core design choice of the Moirai papers: rather than one token per time step, the series is patched, and patch_size can be "auto", 8, 16, 32, 64 or 128. Moirai-MoE is the variant with a mixture-of-experts layer, described in its own arXiv preprint and released as small and base checkpoints.

Forecasts are sampled, not deterministic. num_samples=100 in the README example means the model returns 100 trajectories, which is what makes quantile output and probabilistic scoring possible downstream. The dimensions feat_dynamic_real_dim and past_feat_dynamic_real_dim are read off the dataset object rather than hardcoded, so covariates flow through only if the GluonTS dataset carries them. In the Moirai 2.0 branch of the example, both are set to 0, which is a plain statement that this particular model configuration does not consume covariates.

## Installing uni2ts with pip and running a first zero-shot forecast

The README gives two install paths. The source path clones the repository, creates a virtual environment, and installs the package in editable mode with the notebook extra, which pulls in jupyter, ipywidgets and matplotlib. The PyPI path is a single command.

```bash
pip install uni2ts
```

The source route is the one the README walks through step by step, and it is the one you want if you intend to touch the training or fine-tuning code rather than only call the forecast classes.

```bash
git clone https://github.com/SalesforceAIResearch/uni2ts.git
cd uni2ts
virtualenv venv
. venv/bin/activate
pip install -e '.[notebook]'
```

The README also instructs you to create an empty .env file with touch .env; python-dotenv is a declared dependency, so configuration is expected to be read from the environment at runtime.

A first real use is the zero-shot example the README provides. The data is read from a CSV URL into a wide DataFrame, converted to a GluonTS dataset, split so the last TEST steps become the test set, and expanded into rolling windows. The model then downloads weights from the Hub.

```python
import pandas as pd
from gluonts.dataset.pandas import PandasDataset
from gluonts.dataset.split import split
from uni2ts.model.moirai import MoiraiForecast, MoiraiModule

MODEL, SIZE = "moirai", "small"
PDT, CTX, PSZ, BSZ, TEST = 20, 200, "auto", 32, 100

df = pd.read_csv(url, index_col=0, parse_dates=True)
ds = PandasDataset(dict(df))
train, test_template = split(ds, offset=-TEST)
test_data = test_template.generate_instances(
    prediction_length=PDT, windows=TEST // PDT, distance=PDT
)
model = MoiraiForecast(
    module=MoiraiModule.from_pretrained(f"Salesforce/moirai-1.1-R-{SIZE}"),
    prediction_length=PDT, context_length=CTX, patch_size=PSZ,
    num_samples=100, target_dim=1,
    feat_dynamic_real_dim=ds.num_feat_dynamic_real,
    past_feat_dynamic_real_dim=ds.num_past_feat_dynamic_real,
)
```

What you should see: the first run downloads the checkpoint, and subsequent calls reuse the cached weights. The README's example notebook example/moirai_forecast_pandas.ipynb is the place to look for the plotting step, since the README's own snippet is truncated before it constructs the predictor.

## Where Uni2TS gets in the way: dependency pins, alpha status and missing rollback guidance

The dependency bounds in pyproject.toml are the first real obstacle. torch is pinned to >=2.1,<2.5, numpy to ~=1.26.0, gluonts to ~=0.14.3, and jax[cpu] is pulled in unconditionally even though the README's inference path is PyTorch. If your project already runs a newer PyTorch or NumPy 2.x, you are looking at a separate environment rather than an addition to your existing one. That is a deliberate reproducibility choice for a research codebase, but it is a cost you pay at install time.

The project classifies itself as "Development Status :: 3 - Alpha" in pyproject.toml. Treat that literally. The README does not document rollback, deprecation or migration between model generations, and it does not describe how to revert a fine-tune or restore a previous checkpoint state. The release history shows the shape of the problem: 2.0.0 arrived on 2025-11-04, more than a year after 1.2.0 on 2024-11-28, and the codebase carries separate project directories per model generation (project/moirai-1, project/moirai-moe-1, project/benchmarks). Old examples stay in the tree rather than being rewritten, which is helpful for reproducibility and unhelpful if you assume everything under example/ targets the current model.

A more concrete failure mode sits in the example itself. The README's Moirai 2.0 branch constructs Moirai2Forecast with hardcoded prediction_length=100 and context_length=1680 and zero covariate dimensions, while the surrounding variables PDT and CTX are ignored. Copy that branch and change PDT, and your forecast horizon will not change. The README does not flag this.

## Uni2TS against a statistical baseline and against a task-specific model

The honest alternative for many readers is not another transformer. It is a classical or gradient-boosted forecaster fitted per series, which needs no GPU, no checkpoint download, and no version-pinned environment. The difference in approach is fundamental: Uni2TS amortises training across many series once and then applies the result zero-shot, while a per-series model spends its capacity on one series and has no notion of transfer. For a small number of long, stable series, the per-series approach is often the better engineering choice, and nothing in the README claims otherwise.

The closer alternative inside the same research space is a task-specific transformer trained on your own data with your own architecture. That gives you full control over covariates, loss and tokenisation, at the cost of the pre-training corpus that Moirai was built on. Uni2TS's own benchmark directory makes this comparison concrete: it ships evaluation code for TimesFM, Chronos and VisionTS on Monash, LSF and PF, so the project itself expects you to run competitors through the same harness rather than take a claim on faith. If your question is "which of these models wins on my data", that directory is the intended path, and it is more useful than any single-model tutorial.

## Maintenance, upgrade cost and what Apache-2.0 covers here

The repository is not archived, and the last push was on 2026-06-02. There is no stated support window and no changelog file at the top level; release notes exist as tagged releases, with 2.0.0 described as the Moirai 2.0 release. Upgrading across the 1.x to 2.0 line means moving between model generations, since Moirai 2.0 checkpoints are loaded through a different class (Moirai2Forecast, Moirai2Module) than Moirai 1.1 or Moirai-MoE. Budget for re-validating your evaluation pipeline, not just bumping a version string.

Licensing is Apache-2.0, per the badge and LICENSE.txt. That is a permissive licence, and the repository also carries AI_ETHICS.md and SECURITY.md at the top level. Model weights live on Hugging Face under the Salesforce organisation rather than in this repository, so the licence that applies to a checkpoint is the one on its model card, not the one on this code. Check both before shipping anything. This is a description of what the files say, not legal advice.

## Conclusion

Adopt Uni2TS if you want to run or fine-tune Moirai checkpoints inside a PyTorch and GluonTS pipeline, and you accept an alpha-classifier package whose dependencies are pinned to torch>=2.1,<2.5, numpy~=1.26.0 and gluonts~=0.14.3. Do not adopt it if you need a stable API, a CPU-only laptop workflow, or a maintained release cadence: the last push was on 2026-06-02 and the most recent release, 2.0.0, shipped on 2025-11-04. Before committing, verify that your environment can satisfy those version bounds, decide whether you need the [notebook] extra or the build-lotsa extra, and check the Apache-2.0 LICENSE.txt plus AI_ETHICS.md against how you intend to use the model outputs.

## FAQ

### Is time series forecasting hard?

The Uni2TS README presents pre-trained universal transformers as a way to forecast new series without training a model per dataset, which is the difficulty the library is aimed at. It does not make a general claim about how hard the problem is.

### What is the best model for time series forecasting?

Uni2TS does not answer this directly. It ships evaluation code for TimesFM, Chronos and VisionTS on the Monash, LSF and PF benchmarks, and points to the GIFT-Eval leaderboard, so the project expects you to compare models on the benchmark rather than accept a single recommendation.

### Is LSTM used for time series forecasting?

The README and pyproject.toml describe Uni2TS as a PyTorch library for transformer-based universal time series forecasting, with Moirai, Moirai-MoE and Moirai 2.0 checkpoints. No LSTM model is mentioned in the repository's documentation.

### What are the four types of time series?

Uni2TS does not classify time series into four types. The README's example instead treats a wide DataFrame as a collection of series, one per column, and converts it into a GluonTS dataset for splitting and rolling evaluation.

## Sources

- [Issues](https://github.com/SalesforceAIResearch/uni2ts/issues)
- [License: Apache-2.0](https://github.com/SalesforceAIResearch/uni2ts/blob/main/LICENSE)
- [README](https://github.com/SalesforceAIResearch/uni2ts/blob/main/README.md)
- [Releases](https://github.com/SalesforceAIResearch/uni2ts/releases)
- [SalesforceAIResearch/uni2ts on GitHub](https://github.com/SalesforceAIResearch/uni2ts)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/salesforceairesearch-uni2ts