# TorchEEG: a plug-and-play EEG analysis layer on top of PyTorch

> TorchEEG packages benchmark EEG datasets, preprocessing transforms, dataset partitioning and published deep learning models behind one PyTorch-shaped API, so a researcher can reproduce a paper's pipeline without writing the data plumbing. The cost is a hard dependency set, an LMDB on-disk cache, and a release history that has been quiet since 2024.

**torcheeg/torcheeg** — TorchEEG is a library built on PyTorch for EEG signal analysis.

- Repository: https://github.com/torcheeg/torcheeg
- Stars: 582 · Forks: 75
- Language: Python
- License: NOASSERTION
- Published: 2026-10-22 · Updated: 2026-10-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/torcheeg-torcheeg

## The problem: every EEG paper re-implements the same plumbing

TorchEEG is a library built on PyTorch for EEG signal analysis, and the stated aim is to provide a plug-and-play EEG analysis tool so researchers can quickly reproduce EEG analysis work and start new EEG analysis research without paying attention to technical details unrelated to the research focus.

That is a narrow and honest scope. The library is not a new modelling contribution. It is the layer between a dataset on disk and a training loop, which in practice means a lot of code that every paper in the field would otherwise write again.

The first piece is a unified data input-output format. TorchEEG specifies a unified IO and implements commonly used EEG databases, so users can quickly access benchmark datasets and define new custom datasets. The datasets defined so far include emotion recognition and so on.

The second piece is preprocessing. The library provides the preprocessing methods commonly used for EEG signals according to papers published in the field, and offers plug-and-play APIs for both offline and online processing. The difference is a practical one that matters for training time. Offline processing lets you process once and use the result any number of times, which speeds up the training process, while online processing saves time when you are creating new data processing methods and want to see their effect immediately.

The third piece is models. TorchEEG provides deep learning models following published papers for EEG analysis, including convolutional neural networks, graph convolutional neural networks and Transformers.

The project is MIT licensed according to the setup.py, the last push was on 2026-10-20, and the released versions are v1.1.3 on 2024-12-23, v1.1.2 on 2024-05-06 and v1.1.1 on 2024-01-03.

## The five modules, and the disk cache underneath them

The library is organised as five modules, and the documentation links to each one.

torcheeg.io is the set of unified input and output APIs used to store the processing results of the various EEG databases, for more efficient and convenient use. torcheeg.datasets is the packaged benchmark dataset implementation, providing a multi-process preprocessing interface. torcheeg.transforms holds the extensive EEG preprocessing methods that help users extract features, construct EEG signal representations and connect to commonly used deep learning libraries. torcheeg.model_selection provides extensive dataset partitioning methods for users to experiment with different settings. And torcheeg.models is the baseline method reproduction module.

The io module is the interesting one, because it is what the rest of the library stands on. All the datasets rely on a set of efficient IO APIs to store data preprocessing results on disk and read them quickly during training, and data preprocessing and storage support multiprocessing, which the README notes speeds things up.

That design is what makes the offline and online distinction work. An offline transform pipeline writes its output through the io layer, so the second run of a training script reads a preprocessed file instead of redoing the filtering and windowing. The io layer is backed by lmdb, which appears in the dependency list, so the on-disk store is an LMDB database rather than a pile of files.

The consequence is that TorchEEG wants to own a cache directory on your machine and to fill it. On a workstation that is fine and can be a large speedup. In a container with a small ephemeral volume, or on a cluster where each job lands on a different node, that cache has to be planned for rather than discovered.

The model_selection module deserves a note too, because the partitioning method is where reproducibility lives in EEG work. A dataset split that differs from the paper's makes a reproduced number meaningless, and having a single place where the split is defined is worth more than it looks.

## Installation: PyTorch first, then TorchEEG, then the optional plugins

TorchEEG depends on PyTorch, and the README asks you to complete the PyTorch installation yourself according to your system and CUDA version, with the official PyTorch installation page referenced. The examples given in the README are for PyTorch 1.11.0, in both conda and pip form, with CPU and GPU variants.

That version choice is the first thing to check, and it is worth reading against the current PyTorch releases rather than copying the command. The library itself is installed separately, and there are three documented routes.

Conda is supported, and the channel is a personal one rather than conda-forge:

```bash
conda install -c tczhangzhi -c conda-forge torcheeg
```

Pip is the other stable route:

```bash
pip install torcheeg
```

And for the latest unreleased features, a nightly install straight from the main branch:

```bash
pip install git+https://github.com/torcheeg/torcheeg.git
```

The graph algorithm support is a separate plugin, and it is optional in a way the README states explicitly. TorchEEG provides plugins related to graph algorithms for converting EEG in datasets into graph structures and analysing them using graph neural networks, and this part of the implementation relies on PyG. If you do not use graph-related algorithms, you can skip this part of the installation. The pip command for it installs torch-scatter, torch-sparse, torch-cluster, torch-spline-conv and torch-geometric, with separate CPU and GPU wheel indexes.

So the install order in practice is PyTorch first, then TorchEEG, and then the pieces your project actually needs. The graph plugin is the one most projects will want to skip, and the README tells you that skipping it is fine rather than presenting it as a warning.

## The dependency list is where the real constraints live

The setup.py in the repository lists the runtime dependencies in full, and they are worth reading before you install, because they explain a lot about the design.

The core requirements are tqdm for progress reporting, numpy and pandas for the data layer, xlrd for spreadsheet input, scikit-learn for the classical parts of the pipeline, lmdb for the on-disk store, einops for tensor rearranging, mne for the EEG signal handling, xmltodict for the metadata formats the datasets use, networkx for graph construction, PyWavelets for the wavelet transforms, spectrum for spectral analysis, torchmetrics for the metrics, mne_connectivity for connectivity measures, pytorch-lightning as the training harness, wfdb for the PhysioBank waveform format, and filelock for coordinating access to the cache.

Two of those pins deserve a closer look. scipy is constrained to a range, >=1.7.3 and <= 1.10.1, which is a narrow window that will conflict with many current environments. And torchmetrics and pytorch-lightning are unpinned, which means the resolver takes whatever satisfies the rest.

The extras are where the optional features live, and the naming is clear enough to plan against. The model extra carries torch-scatter, torch-sparse and torch_geometric, the graph algorithm support. The dataset extra carries moabb, the standard battery of EEG datasets. The trainer extra carries torch-fidelity and the image metrics of torchmetrics. The transforms extra carries soxr for high quality resampling. And the test extra carries pytest.

The package also requires Python 3.7 or later, and the version is read from the setup module as 1.1.3, matching the newest release.

One inconsistency is worth flagging rather than glossing over. The dataset plugin requirement is declared twice in the file, once as a named list and once as an assignment to the same name, with the second declaration overwriting the first. Both happen to hold the same requirement, moabb>=0.5.0, so nothing breaks today, but it is the kind of copy and paste that produces a surprising bug the day the two lists diverge.

## The examples, and what they tell you about the intended workflow

The examples directory is the most direct evidence of how the library is meant to be used, and the file names map to the modules.

There are per-dataset scripts, examples_amigos_dgcnn.py for the AMIGOS dataset with a deep graph convolutional network, examples_deap_cwgangp.py for DEAP with a CWGG model, examples_dreamer_tsception.py for DREAMER with a TSception model, examples_seed_ccnn.py for SEED with a continuous convolution network, and examples_dtu_darnet.py for the DTU dataset with a DARNet model. The naming pattern is consistent: a dataset, a model, and a script that wires them together.

Then there are the scripts that isolate one part of the pipeline. examples_datasets.py covers the dataset layer, examples_transforms.py the preprocessing, examples_model_selection.py the partitioning, examples_models.py the model zoo, examples_pipeline.py the assembled pipeline, examples_trainers.py the training loop, and examples_vanilla_torch.py the comparison against plain PyTorch, which is the baseline you want to see before you accept that a complicated pipeline is earning its keep.

Two of the remaining scripts are about research questions rather than a single component. examples_seed_domain_adaption.py is a domain adaptation experiment on SEED, and examples_transfer_mahnob_2_deap.py is a transfer learning run from MAHNOB-H to DEAP.

The datasets themselves are named in the README with their source papers. The AMIGOS dataset comes from Miranda-Correa et al., on affect, personality and mood research for individuals and groups. DREAMER comes from Katsigiannis et al., a database for emotion recognition through EEG and ECG signals from wireless low-cost off-the-shelf devices. SEED comes from Zheng et al., on critical frequency bands and channels for EEG-based emotion recognition with deep neural networks. And DEAP is listed as well.

The paper is published as well, hosted on ScienceDirect with the identifier S0957417424004159, which places it in the expert systems with applications area, and the README links the examples directory and the readthedocs documentation alongside it.

## Conclusion

Adopt TorchEEG if you are reproducing published EEG work and want the dataset loading, preprocessing and baseline models already assembled, since that is exactly what the library is for. Do not adopt it for a new production pipeline without checking the dependency pins, because the setup pins scipy to a narrow range and the README's own install instructions target PyTorch 1.11, which is old. Before you build, read the extras list, since graph models, moabb datasets, soxr resampling and the image metrics for the trainer each live in a separate extra, and check the CHANGELOG before assuming the latest PyPI release matches the current documentation.

## FAQ

### What is TorchEEG and what does it give you?

It is a PyTorch library for EEG signal analysis that provides a unified data input and output format, implementations of commonly used EEG benchmark datasets, preprocessing methods, dataset partitioning methods and deep learning models following published papers, so researchers can reproduce EEG work without writing the surrounding plumbing.

### How do I install TorchEEG?

Install PyTorch first for your system and CUDA version, then either conda install -c tczhangzhi -c conda-forge torcheeg, pip install torcheeg, or pip install git+https://github.com/torcheeg/torcheeg.git for the latest unreleased features from the main branch.

### What is the difference between offline and online preprocessing in TorchEEG?

Offline processing lets you process once and use the result any number of times, which speeds up training, while online processing saves time when you are creating new data processing methods. Both are offered as plug-and-play APIs.

### Do I need the PyG plugin to use TorchEEG?

No, not if you avoid graph-related algorithms. The README says the plugin for converting EEG in datasets into graph structures and analysing them with graph neural networks relies on PyG, and that you can skip this part of the installation if you do not use graph algorithms.

### Which optional dependencies does TorchEEG provide as extras?

The model extra carries torch-scatter, torch-sparse and torch_geometric, the dataset extra carries moabb, the trainer extra carries torch-fidelity and the torchmetrics image metrics, the transforms extra carries soxr for resampling, and the test extra carries pytest. The core install includes lmdb for the on-disk store, mne, PyWavelets, networkx, torchmetrics, pytorch-lightning and wfdb.

## Sources

- [Issues](https://github.com/torcheeg/torcheeg/issues)
- [README](https://github.com/torcheeg/torcheeg/blob/main/README.md)
- [Releases](https://github.com/torcheeg/torcheeg/releases)
- [torcheeg/torcheeg on GitHub](https://github.com/torcheeg/torcheeg)

---

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