Installation#

This guide covers the installation of eegprep and its dependencies.

System Requirements#

Before installing eegprep, ensure your system meets the following requirements:

Python: 3.10 or higher
uv: Default package and environment manager for source installs and development
pip: Optional fallback for published package installs
conda: Optional environment manager when required by a local setup
Operating System: Linux, macOS, or Windows
RAM: Minimum 4GB (8GB+ recommended for large datasets)
Disk Space: At least 500MB for installation and dependencies

Installation Methods#

Using uv (Recommended)#

For a project managed by uv, add eegprep with:

uv add eegprep

To include all optional EEGPrep dependencies:

uv add "eegprep[all]"

Using pip#

Published EEGPrep packages can also be installed with pip in non-uv environments:

pip install eegprep

From Source#

To install eegprep from source for development:

git clone https://github.com/sccn/eegprep.git
cd eegprep
uv sync --group dev

uv sync creates the project environment, installs EEGPrep in editable mode, and uses uv.lock for reproducible dependency resolution. The development environment includes the GUI and console runtime dependencies, so a fresh checkout can immediately launch uv run eegprep-console --full.

To develop or build documentation from source, include the docs extra:

uv sync --group dev --extra docs

Optional Dependencies#

eegprep has several optional dependencies that enable additional functionality:

PyTorch (for GPU acceleration)#

To use GPU-accelerated processing with PyTorch:

uv add torch

For CUDA support (NVIDIA GPUs):

uv add torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118

For CPU-only PyTorch:

uv add torch --index-url https://download.pytorch.org/whl/cpu

AMICA#

EEGPrep can run AMICA through eeg_amica and ICAAlgorithm='amica', but published EEGPrep packages do not include AMICA binaries. This keeps Python package downloads smaller and avoids shipping platform-specific executables.

To use AMICA, install or download an AMICA executable separately, then provide it in one of these ways:

export AMICA_BINARY=/path/to/amica15ub

or pass the path directly:

eeg = eeg_amica(eeg, amica_binary="/path/to/amica15ub")

Source checkouts may contain development binaries under src/eegprep/bin/. Those files are for local development and tests, not for package distribution.

Documentation Building#

To build the documentation locally:

uv sync --group dev --extra docs
uv run --no-sync sphinx-build -b html docs/source docs/_build/html

The docs/Makefile target is also available:

uv run --no-sync make -C docs html

All Optional Dependencies#

To install all optional dependencies at once:

uv add "eegprep[all]"

Or with specific extras:

uv add "eegprep[torch,gui,docs]"

Verification#

After installation, verify that eegprep is correctly installed by running:

import eegprep
print(eegprep.__version__)

You should see the version number printed without any errors.

To verify all core modules are available:

from eegprep import (
    pop_loadset,
    pop_saveset,
    clean_artifacts,
    iclabel,
    pop_resample,
    pop_reref,
    topoplot
)
print("All core modules imported successfully!")

Troubleshooting#

Import Errors#

Problem: ModuleNotFoundError: No module named 'eegprep'

Solution: Ensure eegprep is installed:

uv add eegprep

If installing from source, ensure you’re in the correct directory and use:

uv sync --group dev

Version Conflicts#

Problem: Conflicts with NumPy, SciPy, or other dependencies

Solution: Create a fresh virtual environment:

uv venv eegprep_env
source eegprep_env/bin/activate  # On Windows: eegprep_env\Scripts\activate
uv pip install eegprep

PyTorch Installation Issues#

Problem: PyTorch installation fails or GPU not detected

Solution:

Check your CUDA version:

nvidia-smi

Install the matching PyTorch version from https://pytorch.org/get-started/locally/
Verify PyTorch installation:

import torch
print(torch.cuda.is_available())

EEGLAB File Format Issues#

Problem: Cannot read .set files

EEGPrep reads .set files directly with SciPy (scipy.io.loadmat) and h5py for newer MATLAB v7.3 files, and writes them with scipy.io.savemat. These libraries are installed automatically, so a load failure is almost always a path or format problem rather than a missing dependency.

Solution: Check that the path points at an existing .set file and that any companion .fdt data file sits next to it:

from pathlib import Path
from eegprep import pop_loadset

path = Path("sub-01_task-rest_eeg.set")
assert path.is_file(), f"no such file: {path}"
EEG = pop_loadset(str(path))

Memory Issues#

Problem: Out of memory errors when processing large datasets

Solution:

Process data in chunks or epochs
Reduce the number of channels if possible
Increase available RAM or use a machine with more memory
Use GPU acceleration if available

Getting Help#

If you encounter issues not covered here:

Check the Frequently Asked Questions section
Review the troubleshooting sections in this installation guide and FAQ
Visit the GitHub Issues page
Check the API Reference

Next Steps#

After successful installation, proceed to the Quick Start guide to learn how to use eegprep.