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:

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

On Windows use:

.\init.bat
cmake --build build\developer-dynamic --parallel

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

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.

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 2022 (Visual Studio 2022 Community or higher. 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:
   • Windows: e.g. C:\Qt\6.11.0\msvc2022_64\bin
   • Linux: e.g. $HOME/Qt/6.11.0/gcc_64/bin — also add the lib folder to LD_LIBRARY_PATH
   • macOS: e.g. $HOME/Qt/6.11.0/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_project.sh

# Windows
.\scripts\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

Example — build everything in Release mode:

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

# Windows
.\scripts\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 a kit with your Qt 6 installation — e.g. Desktop Qt 6.11.0 MSVC2022 64bit.
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/apps 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/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_project.sh all

# Windows
.\scripts\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 cross-platform deployment script:

./scripts/deploy.bat dynamic pack    # dynamic linking (recommended for development)
./scripts/deploy.bat static pack     # static linking

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