Braindecode: deep learning on raw EEG, ECoG and MEG signals

What Braindecode solves for EEG and MEG researchers

Raw electrophysiological recordings are not images. A recording arrives as a set of channels sampled over time, with a sampling rate, a montage, and often a BIDS sidecar describing events. Turning that into tensors a convolutional network can consume involves resampling, filtering, epoching around events, and deciding which channels to keep. Braindecode bundles those steps with model implementations so the same object can carry a recording from a dataset fetcher to a training loop.

The README states the intended audience directly: "For neuroscientists who want to work with deep learning and deep learning researchers who want to work with neurophysiological data." That is a narrower group than the topic list suggests. If you already train PyTorch models and have never handled a montage, Braindecode is the part that teaches you the domain conventions. If you are a neuroscientist who has only used classical decoders, it is the part that gives you network architectures without asking you to invent one.

How the toolbox is layered: MNE, skorch and PyTorch

The dependency list in pyproject.toml is the architecture. mne>=1.11.0 is required, and the comment notes that matplotlib, numpy and scipy arrive through it. mne_bids>=0.18 is a separate explicit dependency, so BIDS-formatted datasets are a first-class input path rather than an afterthought. skorch>=1.3.0 sits above torch, which is what lets a network be wrapped in an estimator with fit and predict semantics. torchaudio is pulled in alongside torch.

That layering has a practical consequence. Braindecode does not define its own array container. A recording is an MNE object, and the deep learning models are torch modules. The library's job is the seam between them, plus the dataset fetchers, augmentations and visualisation utilities the README lists. When something breaks, the failure is usually in one of the three layers, and knowing which one owns the object in your traceback matters more than knowing Braindecode itself.

Python support is declared as 3.11 through 3.14, and requires-python is >=3.11. If your lab environment is pinned to an older interpreter, that constraint will decide the question before any modelling does.

Installing Braindecode with pip and running a first model

The README gives a three-step order, and the order is not decorative. PyTorch must be installed first, from pytorch.org, and the README notes you do not need torchvision. Then, only if you want to download EEG datasets from MOABB, install that separately. Then install the release.

Start with PyTorch from its own index, then the toolbox:

pip install braindecode

If you plan to pull datasets through MOABB rather than reading your own files, the README's second step is:

pip install moabb

For the development version, the README points to the contributing page on GitHub rather than giving a command, so a source install is documented there and not in the README. Documentation lives at braindecode.org in stable and dev versions.

The repository ships examples rather than a quickstart script. Top-level examples/ is split into advanced_training/, applied_examples/, datasets_io/ and model_building/, and the related searches for a Braindecode tutorial map onto those directories. datasets_io/ is where you would look to see how a recording becomes a dataset object; model_building/ is where the architectures are assembled. Reading one file in each is a faster orientation than reading the API reference top to bottom.

Where Braindecode is the wrong tool

The package classifier in pyproject.toml says Development Status :: 3 - Alpha. That is the project's own label, and it should shape expectations. An alpha classifier is not a statement about code quality, but it does mean interfaces can move between minor releases, and the release history shows v1.7.0, v1.8.0 and v1.8.1 landing within roughly two months. Pinning a version is the difference between a reproducible analysis and a debugging session.

Two other boundaries are worth stating plainly. First, Braindecode is for electrophysiological signals. The README names EEG, ECoG and MEG. If your data is fMRI or fNIRS volumes, the preprocessing and model zoo here do not apply, even though the phrase deep learning for brain data might lead you to expect otherwise. Second, the README does not document rollback, migration between versions, or a deprecation policy, so upgrading a trained pipeline is not something the documentation currently supports with a procedure.

There is also a licensing boundary. The README states the project is primarily BSD-3-Clause but that some components carry CC BY-NC 4.0, CC BY-NC-SA 4.0, MIT or Apache-2.0, and it directs you to LICENSE and NOTICE for the per-file list. A non-commercial component inside a permissive project is a real constraint for anyone building a product, and it is not visible from the repository's headline licence alone.

Braindecode compared with MOABB and a plain MNE plus PyTorch stack

MOABB is the closest thing to an alternative, and the difference is scope rather than quality. MOABB is a benchmarking framework: its purpose is to run many pipelines across many public datasets and compare them under a common protocol. The README treats it as an optional companion, installed separately with pip install moabb, and used to download EEG datasets. If your question is which decoder wins on a fixed set of datasets, MOABB answers it. If your question is how to build and train one network on your own recordings, Braindecode answers it. They overlap at the dataset fetcher and diverge everywhere else.

The other alternative is assembling MNE-Python and PyTorch yourself. MNE handles reading, filtering, epoching and montages; PyTorch handles the model and the optimiser. That stack is fully under your control and has no additional abstraction. What you give up is the skorch integration, the implemented architectures, the augmentations and the dataset fetchers that Braindecode provides, and you would be writing the glue that the library already maintains. For a one-off experiment, the glue is cheap. For a lab that will run the same pipeline on new recordings for years, maintaining it is not.

Maintenance, upgrades and what the licence actually covers

The repository is not archived, and the last push was on 2026-09-09. The most recent release listed is v1.8.1 on 2026-08-31. That is a project with current activity, and the release cadence across v1.7.0, v1.8.0 and v1.8.1 suggests minor versions arrive frequently enough that an unpinned dependency will drift during a study.

Upgrade cost is dominated by the dependency floor, not by Braindecode's own code. mne>=1.11.0, skorch>=1.3.0, torch>=2.0 and mne_bids>=0.18 are all lower bounds, so a fresh install may resolve to newer versions of any of them. Reproducing a published result means pinning all four plus Braindecode itself. The README does not describe a compatibility matrix between Braindecode versions and MNE versions, so that work is yours.

On licensing, BSD-3-Clause permits commercial use and modification with attribution. The complication is the additional components the README names under CC BY-NC 4.0 and CC BY-NC-SA 4.0. Those are non-commercial licences. Because the README defers to LICENSE and NOTICE for the per-file list, you cannot determine from the package metadata alone whether the specific model or dataset loader you depend on is permissively licensed. Check the files for the components you actually import. This is a factual boundary, not legal advice, and a commercial deployment should have the per-file list reviewed before release.

Editorial conclusion

Adopt Braindecode if your data is already in MNE or BIDS form and you want published EEG architectures with a scikit-learn style training loop rather than a bespoke training script. Do not adopt it if you need a clinical-grade pipeline, if you cannot install PyTorch, or if your signals are not electrophysiological. Before committing, check the per-file licence list in LICENSE.txt and NOTICE.txt, and confirm that the model you intend to use is covered by BSD-3-Clause rather than one of the non-commercial licences the README names.

Frequently asked questions

Official sources

1. braindecode/braindecode on GitHub
2. License: BSD-3-Clause
3. Project website
4. README
5. Releases