# catalyst-team/catalyst: the Runner API on a 2022 release line

> catalyst-team/catalyst fills in the PyTorch training loop around your own model, with dl.SupervisedRunner binding four batch-dict keys. The catch is timing: the newest release is v22.04 from 2022-04-29 and the default branch was pushed to on 2026-07-08.

**catalyst-team/catalyst** — Accelerated deep learning R&D

- Repository: https://github.com/catalyst-team/catalyst
- Website: https://catalyst-team.com
- Stars: 3,386 · Forks: 397
- Language: Python
- License: Apache-2.0
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/catalyst-team-catalyst

## A 2022 release line under a branch pushed in 2026

The three releases listed for this project are v22.02 on 2022-02-13, v22.02.1 on 2022-02-27 and v22.04 on 2022-04-29. The numbering is a calendar version, so the tag itself carries a date and promises no semantic upgrade path. The newest of them is more than four years older than the 2026-07-08 commit on the default branch, and the repository is not marked archived. That combination decides what lands on your machine. `pip install -U catalyst` resolves to whatever the package index holds today, which the README never states, while the branch itself is a separate install line further down the same section. A tutorial written against master and a tutorial written against the packaged release can therefore describe different code behind the same import. The rendered README carries the same drift. It repeats one continuous-integration badge six times in a row, and its banner links a Slack workspace named catalyst-team-devs while the step-by-step guide links a different one, catalyst-team-core.

## Three install commands and three different targets

The generic line appears twice, once in the getting-started block and once under Installation, and both read `pip install -U catalyst`. The specialized lines sit inside a details block that warns extra requirements might apply, and there are three of them:

```bash
pip install -U catalyst
pip install catalyst[ml]         # installs ML-based Catalyst
pip install catalyst[cv]         # installs CV-based Catalyst
# master version installation
pip install git+https://github.com/catalyst-team/catalyst@master --upgrade
```

The first two differ from the generic line only by the extra name, and their comments say what each one pulls in. The third is not an extra at all: it installs from the branch, which is the line you want when the packaged release is older than the PyTorch you already run. Notice how little of the extras surface is documented. Two group names appear here. The package metadata names many more, one requirement file each, and nothing above the packaging script tells you which ones exist, what they drag in, or which PyTorch version they expect.

## The quickstart ends at a comment reading `model trai`

The getting-started block is the only worked example in the visible documentation, and it stops one line into the training call. Everything before that line is complete:

```python
import os
from torch import nn, optim
from torch.utils.data import DataLoader
from catalyst import dl, utils
from catalyst.contrib.datasets import MNIST

model = nn.Sequential(nn.Flatten(), nn.Linear(28 * 28, 10))
criterion = nn.CrossEntropyLoss()
optimizer = optim.Adam(model.parameters(), lr=0.02)
loaders = {
    "train": DataLoader(MNIST(os.getcwd(), train=True), batch_size=32),
    "valid": DataLoader(MNIST(os.getcwd(), train=False), batch_size=32),
}
```

The loaders dictionary keys the two data loaders train and valid, and the dataset class comes from catalyst.contrib.datasets rather than from a separate package. The import line pulls in dl and utils, but only dl is used before the snippet ends. Then the runner:

```python
runner = dl.SupervisedRunner(
    input_key="features", output_key="logits", target_key="targets", loss_key="loss"
)
```

That is the whole example. The runner gets constructed and the page stops, at a comment that begins model trai and breaks there. So the documented path to a first result is: assemble the pieces yourself, hand them to the runner, and find the call that starts training somewhere else. The step-by-step guide above points at notebook tutorials, at minimal examples, at the blog posts under catalyst-team.com/post/ and at the Deep Learning with Catalyst course, which is where the missing line is meant to come from.

## Four string keys are the whole contract with your dataset

`dl.SupervisedRunner` takes four arguments in that example and all four are strings: input_key, output_key, target_key and loss_key. They are names in the batch dictionary your data loader produces. Whatever your dataset returns has to use those names, because the runner reads the model input, the model output, the target and the loss term through them. That is the entire join between your code and the framework, and it is four lines long. What the runner then does with those entries gets one sentence in the overview: a training loop with metrics, early stopping and model checkpointing, without the boilerplate. The keys the metrics are written under are not in the visible example, and neither are the callback classes, so the part you can read tells you how to hand data in and leaves the naming of everything the runner writes to the documentation edition you install. For an existing PyTorch codebase the migration is mostly typing four strings correctly. For loaders that emit tuples rather than dictionaries it is a larger change than the README implies.

## The Docker tag comes from a hash of the dependency files

The Makefile derives its image tag from a script rather than from git or from the package version. `PYTHON ?= python` and `TAG=$(shell ${PYTHON} docker/collect_dependencies_hash.py)`, and both the docker and docker-dev targets build with the tag `${REPO_NAME:-catalyst}:${TAG:-latest}` from ./docker/Dockerfile with --no-cache, passing PYTORCH_TAG, CATALYST_DEV, CATALYST_CV, CATALYST_ML, CATALYST_OPTUNA, CATALYST_ONNX and CATALYST_ONNX_GPU as build arguments. Two checkouts whose requirement files match get the same tag even when the source differs, and no version number goes into the tag, so an image built from a moved branch can carry the name of the image before it. The clean target removes build/ and force-removes catalyst:latest and catalyst-dev:latest by those literal names, so an image built under your own REPO_NAME is not what clean removes. The two targets a contributor reaches for first are:

```bash
install-from-source:
	pip uninstall catalyst -y && pip install -e ./

check:
	catalyst-make-codestyle -l 89
	catalyst-check-codestyle -l 89
```

install-from-source uninstalls the packaged catalyst before the editable install, which is the right order and the reason the target exists. The check target is where the next section starts.

## Lint configuration lives in another repository at a 2021 tag

pyproject.toml holds two settings and both of them point outward. The nitpick style is a raw URL into a different repository, pinned to the v21.09.2 tag of catalyst-team/codestyle, and black is set to a line length of 89. The Makefile agrees with black on the width and calls two commands, catalyst-make-codestyle and catalyst-check-codestyle, neither of which any extra the README names installs. The rules your pull requests are judged by therefore live in a file fetched over the network at a fixed 2021 revision, and the commands that apply them are not part of the package. That is a defensible way to hold one style across several repositories, and it is also a dependency on somebody else's tag staying where it is. The third contributor target, check-docs, runs bash ./bin/workflows/check_docs.sh, which keeps the documentation build honest but says nothing about which release the published docs correspond to.

## Eleven extras groups, one requirements file each

setup.py is where the packaging facts live. NAME is catalyst, DESCRIPTION reads Catalyst. Accelerated deep learning R&D with PyTorch., the author is Sergey Kolesnikov with a scitator@gmail.com contact address, and REQUIRES_PYTHON is >=3.7.0. Three helpers do the reading. load_requirements opens a file under requirements/ and splits it into lines, load_version execs catalyst/__version__.py, load_readme prefixes a newline to README.md. The docstring on the first one says Docs? Contribution is welcome., which is the project's own note that those requirement files are undocumented. The extras dictionary maps a group name to one of those files, and eleven keys are visible: cv, comet, deepspeed, dev, ml, mlflow, neptune, onnx, onnx-gpu, optuna and profiler. The mapping stops in the middle of the profiler call, so the list is open-ended from there. Note that onnx and onnx-gpu are separate groups, so the export path is opt-in per target rather than automatic. On versions, the metadata and the prose agree: setup.py asks for 3.7.0 or newer, the README states Python 3.7+ and PyTorch 1.4+, and the tested list names Ubuntu 16.04, 18.04 and 20.04, macOS 10.15, Windows 10 and the Windows Subsystem for Linux. A floor that old next to a branch pushed in 2026 means the metadata answers a question about Python that current code may not.

## Where Catalyst stops and your own code starts

The README names its own alternative: create something new rather than write yet another train loop. That is the comparison worth making, because Catalyst's contribution sits inside the loop, not around the model. You still write the module, the criterion, the optimizer and the loading of data, and the framework supplies metrics, early stopping and checkpointing. If your loop already exists and works, the case for moving is thin. If you keep rewriting it across projects, four keys are a small enough surface to try. The extras then make a second decision for you: groups named mlflow, neptune, comet and deepspeed pull in external trackers and distributed training stacks, and the visible part of setup.py does not say which one the runner writes to by default, so choosing extras chooses your logging and your launch path at the same time. The examples directory shows the breadth, with catalyst_rl, detection, engines, notebooks, recsys, reinforcement_learning and self_supervised each holding its own subdirectory. Two of them, catalyst_rl and reinforcement_learning, cover one subject under two names, which is the clearest sign in the tree of how often the surface has been rearranged. Breadth is a good reason to read the repository and a poor reason to depend on it.

## Conclusion

Adopt catalyst-team/catalyst if you already write PyTorch, want the loop around your model filled in, and are willing to treat the install as one fixed decision. Skip it if you need a framework whose released version tracks the branch, or if extras such as mlflow, neptune, comet or deepspeed end up deciding your dependency set. Before writing any code, run the install line and diff the four keys dl.SupervisedRunner expects against the batches your own loaders emit, because the newest release this repository lists is 22.04 from 2022-04-29 while the branch moved on 2026-07-08.

## FAQ

### How do I install catalyst-team/catalyst?

The README's generic line is `pip install -U catalyst`, with `pip install catalyst[ml]` and `pip install catalyst[cv]` for the two extras it advertises, and `pip install git+https://github.com/catalyst-team/catalyst@master --upgrade` when you want the branch rather than a release. setup.py declares REQUIRES_PYTHON as >=3.7.0.

### What Python and PyTorch versions does catalyst-team/catalyst need?

The README states Python 3.7+ and PyTorch 1.4+, and setup.py carries the same floor as REQUIRES_PYTHON >=3.7.0. The tested list in the README names Ubuntu 16.04, 18.04 and 20.04, macOS 10.15, Windows 10 and the Windows Subsystem for Linux.

### How do I start a training run with catalyst-team/catalyst?

You build an nn.Module, a criterion and an optimizer, then hand them to dl.SupervisedRunner with input_key, output_key, target_key and loss_key. That example ends at a comment reading model trai, so the call that starts training is not in it. The README points at notebook tutorials, minimal examples, blog posts and the Deep Learning with Catalyst course for that part.

### Which extras does catalyst-team/catalyst declare?

setup.py maps each extra name to a requirement file under requirements/. The visible keys are cv, comet, deepspeed, dev, ml, mlflow, neptune, onnx, onnx-gpu, optuna and profiler, with the mapping cut off inside the profiler entry. The README itself advertises only ml and cv.

### What is the release status of catalyst-team/catalyst?

The newest listed release is v22.04, published 2022-04-29, after v22.02.1 on 2022-02-27 and v22.02 on 2022-02-13. The repository is not archived and its last push was 2026-07-08, so branch work and the release line sit four years apart. The documentation index in the README stops at the 22.02 edition.

## Sources

- [catalyst-team/catalyst on GitHub](https://github.com/catalyst-team/catalyst)
- [License: Apache-2.0](https://github.com/catalyst-team/catalyst/blob/master/LICENSE)
- [Project website](https://catalyst-team.com)
- [README](https://github.com/catalyst-team/catalyst/blob/master/README.md)
- [Releases](https://github.com/catalyst-team/catalyst/releases)

---

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