Build from Source

MNE-CPP uses CMake as its build system and requires C++20 and Qt 6. This guide walks through compiling MNE-CPP from source on Windows, Linux, and macOS.

Prerequisites

Recommended Bootstrap

The quickest way to get a reproducible developer setup is to use the repository init scripts. On Linux, first install the compiler, CMake, Git and the OpenGL and XKB development headers the Qt bundle links against:

sudo apt-get update
sudo apt-get install -y build-essential cmake git libgl1-mesa-dev libxkbcommon-dev

Then, on Linux and macOS:

./init.sh
cmake --build build/developer-dynamic --parallel 4

On Windows use:

.\init.bat
cmake --build build\developer-dynamic --config Release --parallel 4

Visual Studio generators build the Debug configuration unless --config names another one; the downloaded Qt bundle is a Release build. Some translation units need about 2 GB of memory to compile, so a bare --parallel (one job per core, or unlimited with Makefiles) can exhaust the memory of a laptop; raise the job count only as far as memory allows.

Check the result by running an example. On Linux and macOS:

./out/Release/examples/ex_math

On Windows, the Qt libraries must be on the PATH:

set PATH=%CD%\src\external\qt\dynamic\bin;%PATH%
out\Release\bin\ex_math.exe

These scripts download the MNE-CPP-maintained prerelease dependency bundles into src/external/:

• Qt 6 desktop binaries matching your platform and requested linkage
• Eigen 5.0.1 as a clean CMake package bundle
• Skigen — header-only ML library (scikit-learn algorithms on Eigen), cloned from the staging branch

That keeps local development aligned with the dependency artifacts used in CI and release workflows. Qt downloads from the public qt_binaries prerelease tag. Eigen downloads from the public eigen_artifacts prerelease tag. No bundled Eigen copy is shipped in the repository.

What onboarding CI verifies

The commands above run unchanged on clean Ubuntu, macOS and Windows runners every week and whenever the init scripts, dependency versions or this page change. The alternatives below (a Qt Online Installer Qt, the build_project scripts, direct CMake calls, Qt Creator, static linkage) are not run by onboarding CI; only the existence of the scripts they call is checked.

CMake

CMake 3.15 or higher is required.

Compiler

MNE-CPP requires a compiler with C++20 support. The following compilers are tested in CI:

Windows	Linux	macOS
MSVC (Visual Studio 2026 in CI. During installation select the Desktop development with C++ workload.)	GCC 13+ (ships with Ubuntu 24.04)	Apple Clang via Xcode (ships with macOS)

Qt 6

Qt 6 is the only dependency you need to install manually if you choose not to use the init scripts above. Qt 5 is no longer supported.

1. Download and run the Qt Online Installer.
2. Install Qt 6.10 or higher to a path without spaces. During installation, select:
   • The compiler target for your platform (e.g., MSVC 2022 64-bit, Desktop gcc 64-bit, or macOS)
   • Qt Shader Tools (required)
3. After installation, add the Qt bin folder to your PATH: The default Qt version is recorded as QT_VERSION in src/external/external_deps.env.
   • Windows: e.g. C:\Qt\<version>\msvc2022_64\bin
   • Linux: e.g. $HOME/Qt/<version>/gcc_64/bin — also add the lib folder to LD_LIBRARY_PATH
   • macOS: e.g. $HOME/Qt/<version>/macos/bin — also add the lib folder to DYLD_LIBRARY_PATH

Get the Source Code

Fork MNE-CPP's main repository to your own GitHub account. For a detailed guide on how to fork a repository, see the GitHub documentation.

Clone the fork to your local machine:

git clone https://github.com/<YourGitUserName>/mne-cpp.git

Set up a remote pointing to the upstream repository:

git remote add upstream https://github.com/mne-tools/mne-cpp.git

To update to the latest changes:

git fetch --all
git rebase upstream/staging

Compile the Source Code

Via Command Line

Navigate to the mne-cpp root folder. We provide a cross-platform build script that automatically detects your platform, finds Qt, configures CMake, and builds:

# Linux / macOS
./scripts/build/build_project.sh

# Windows
.\scripts\build\build_project.bat

If you ran ./init.sh or .\init.bat first, the build script will also auto-detect the downloaded Qt bundle from src/external/qt/.

Common options:

Option	Description
help	Show all available options
all	Build everything (apps, examples, and tests)
static	Build with static linking
Debug	Build in Debug mode (default is Release)
clean	Remove previous build before building
qt=<path>	Use a custom Qt installation path (Windows: qt <path>)

Example — build everything in Release mode:

# Linux / macOS
./scripts/build/build_project.sh all

# Windows
.\scripts\build\build_project.bat all

Alternatively, you can invoke CMake directly:

cmake -B build -S . -DCMAKE_BUILD_TYPE=Release
cmake --build build --parallel $(nproc)

On Windows with MSVC, first activate the compiler environment, then build:

# Open a Developer Command Prompt for VS 2022, or run:
cmd.exe /c "call ""C:\Program Files\Microsoft Visual Studio\2022\Community\VC\Auxiliary\Build\vcvars64.bat"" && set > %temp%\vcvars.txt"

cmake -B build -S . -DCMAKE_BUILD_TYPE=Release
cmake --build build --config Release --parallel %NUMBER_OF_PROCESSORS%

CMake Options

Option	Default	Description
BUILD_SHARED_LIBS	ON	Build shared (dynamic) libraries
BUILD_APPLICATIONS	ON	Build GUI applications
BUILD_EXAMPLES	ON	Build example programs
BUILD_TESTS	OFF	Build unit tests
BUILD_ALL	OFF	Enable apps, examples, and tests
WASM	OFF	Configure for WebAssembly (see WebAssembly)

Via Qt Creator

1. Open Qt Creator and select File > Open File or Project. Navigate to the mne-cpp root folder and select the top-level CMakeLists.txt.
2. When prompted, select the desktop kit for the Qt version in src/external/external_deps.env.
3. Select Release mode in the lower-left corner.
4. In the Projects pane, right-click the top-level mne_cpp target and select Run CMake.
5. Right-click again and select Build (this may take some time).
6. Once complete, built binaries are located in mne-cpp/out/Release.

Running Applications

From Qt Creator, use the Run button in the lower-left toolbar. From the command line, navigate to out/Release/bin and run the desired application, e.g.:

./mne_scan

Test the Build

To verify your build, download the MNE-Sample-Data-Set and extract it to mne-cpp/out/Release/resources/data/MNE-sample-data. Then run one of the examples, e.g. ex_disp_3D. If the build is correct, a window with a 3D brain visualization and source localization result will appear.

To build and run the unit tests:

# Linux / macOS
./scripts/build/build_project.sh all

# Windows
.\scripts\build\build_project.bat all

cd build/Release
ctest --output-on-failure

Deploy Qt Dependencies

To run compiled applications outside of Qt Creator (e.g. from the terminal or file manager), Qt runtime libraries must be bundled. MNE-CPP provides a deployment script for each platform:

./scripts/deploy/deploy.sh dynamic pack    # macOS/Linux, dynamic linking (recommended for development)
./scripts/deploy/deploy.sh static pack     # macOS/Linux, static linking

.\scripts\deploy\deploy.bat dynamic pack
.\scripts\deploy\deploy.bat static pack

The dynamically linked version is recommended for development. For more details, see the Deployment page.