---
title: Build from Source
sidebar_label: Build from Source
---

# 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

### CMake

[CMake](https://cmake.org/download/) **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](https://visualstudio.microsoft.com/vs/community/) (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](https://developer.apple.com/xcode/) (ships with macOS) |

### Qt 6

Qt 6 is the only external dependency. **Qt 5 is no longer supported.**

1. Download and run the [Qt Online Installer](https://www.qt.io/download-qt-installer).
2. Install **Qt 6.5 or higher** (CI currently tests with Qt 6.10.x) 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.10.2\msvc2022_64\bin`
   - **Linux:** e.g. `$HOME/Qt/6.10.2/gcc_64/bin` — also add the `lib` folder to `LD_LIBRARY_PATH`
   - **macOS:** e.g. `$HOME/Qt/6.10.2/macos/bin` — also add the `lib` folder to `DYLD_LIBRARY_PATH`

## Get the Source Code

Fork [MNE-CPP's main repository](https://github.com/mne-tools/mne-cpp) to your own GitHub account. For a detailed guide on how to fork a repository, see the [GitHub documentation](https://help.github.com/en/github/getting-started-with-github/fork-a-repo).

Clone the fork to your local machine:

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

Set up a remote pointing to the upstream repository:

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

To update to the latest changes:

```bash
git fetch --all
git rebase upstream/v2.0-dev
```

## 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:

```bash
./tools/build_project.bat
```

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:
```bash
./tools/build_project.bat all
```

Alternatively, you can invoke CMake directly:

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

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

```powershell
# 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](wasm.mdx)) |
| `NO_OPENGL` | `OFF` | Disable QOpenGLWidget support |

### 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.10.2 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.:

```bash
./mne_scan
```

## Test the Build

To verify your build, download the [MNE-Sample-Data-Set](https://osf.io/86qa2/download) 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:

```bash
./tools/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:

```bash
./tools/deploy.bat dynamic pack    # dynamic linking (recommended for development)
./tools/deploy.bat static pack     # static linking
```

The dynamically linked version is recommended for development. For more details, see the [Deployment](ci-deployment.mdx) page.
