Installation

Installation is easy.

Two methods, both supported, both lead to the same working MEEGqc. Pick the one that fits your workflow.

Recommended

Method 1. One-click installer

Download the per-OS bootstrap script and double-click it. Brings its own portable Python, builds an isolated environment, and registers a native launcher. Nothing on your system is changed.

Go to the installer guide → For developers

Method 2. Manual install (CLI)

Install Python yourself, create a virtual environment (venv, conda, or uv), and pip install meg-qc (or pip install meeg-qc, the rebrand-aligned wrapper). Useful if you already manage Python environments or want to keep everything inside your existing toolchain.

Go to the manual guide →
Method 1 . One-click installer

Run the bootstrap installer

One ZIP for all three operating systems. Inside is a folder per platform with a single script. Run it once, and MEEGqc shows up as a regular app on your machine.

Supported platforms for the one-click installer
  • macOS: Apple Silicon only (M1, M2, M3, M4 chips). Intel Macs are not supported by the installer.
  • Linux: x86_64 only. ARM / aarch64 is not supported by the installer.
  • Windows: x86_64 only. ARM Windows is not supported by the installer.

On a different architecture? Use Method 2 (manual install). It works on any platform with Python 3.10 to 3.14. Not sure which architecture you have? →

Download installers.zip

Unzip the file, open the folder for your OS, and follow the steps.

The macOS installer is built for Apple Silicon (arm64). On Intel Macs, use Method 2 (manual) instead.

  1. Double-click install_MEEGqc.command inside the MacOS/ folder.
  2. macOS shows an unidentified developer warning. Click Done. The OS has now seen the file and lets you whitelist it.
  3. Open System Settings → Privacy & Security, scroll to the Security section, and click Open Anyway.
  4. Re-double-click the script. A terminal opens and the install runs. 3 to 5 minutes on a typical connection.
  5. Launch MEEGqc from Applications, Launchpad, or Spotlight. The app icon lives at ~/Applications/MEEGqc.app.
Prefer the terminal?

Run ./install_MEEGqc.command directly. Same result, no Gatekeeper dialog.

Built for x86_64. The installer registers MEEGqc in your application menu with the app icon.

  1. Open a terminal in the Linux/ folder.
  2. Make the script executable. 
    chmod +x install_MEEGqc.sh
  3. Run it. 
    ./install_MEEGqc.sh
  4. Launch MEEGqc from your application menu. The entry runs the bundled launcher, which sources the venv for you.
Using the terminal on Linux.

The bootstrap installer keeps Python and MEEGqc inside ~/MEEGqc/env/, so a fresh shell does not see the meegqc command on its PATH. Activate the venv first, then call it: 

source ~/MEEGqc/env/bin/activate
meegqc

Same applies to the CLI verbs run-meegqc, run-meegqc-plotting, globalqualityindex, and get-meegqc-config. If you want them always on PATH, append the activation line to your ~/.bashrc / ~/.zshrc, or symlink the scripts in ~/MEEGqc/env/bin/ into ~/.local/bin/.

XFCE / Thunar users.

Thunar refuses to execute shell scripts on double-click by default. Either run from a terminal, or enable script execution once: 

xfconf-query --channel thunar \
  --property /misc-exec-shell-scripts-by-default \
  --create --type bool --set true

Built for x86_64 (Windows 10 and 11). Places a Desktop shortcut and a Start Menu entry with the MEEGqc icon.

  1. Inside the Windows/ folder, double-click install_MEEGqc.bat.
  2. If SmartScreen shows Windows protected your PC, click More info → Run anyway.
  3. A console opens and the install runs. A MEEGqc shortcut appears on your Desktop and in the Start Menu when finished.
  4. Double-click the Desktop shortcut to launch.
First launch is slower.

The first start pre-compiles the embedded Python and caches dependencies. Subsequent launches are fast.

Under the hood

What does the installer do?

Seven steps, fully automated. Hover a step or let it auto-play to see what the installer is building inside ~/MEEGqc/.

Hover a step to preview, click to pin.
After install

Launch, uninstall, where things land

OSLaunchUninstall
macOS ~/Applications/MEEGqc.app Drag the .app to Trash, then run ~/MEEGqc/uninstall_MEEGqc.command
Linux MEEGqc in the application menu (the entry sources the bundled venv for you). For terminal use, see the Using the terminal on Linux note above. ~/MEEGqc/uninstall_MEEGqc.sh
Windows Desktop shortcut or Start Menu entry MEEGqc Desktop shortcut Uninstall MEEGqc, or %USERPROFILE%\MEEGqc\uninstall_MEEGqc.bat

Where things are installed

OSInstall root
macOS /Users/<you>/MEEGqc/
Linux /home/<you>/MEEGqc/
Windows C:\Users\<you>\MEEGqc\

The folder holds the portable Python, the virtual environment, the launcher, the uninstaller, and an install.log for diagnostics.

Method 2 . Manual (CLI)

Install with pip in your own environment

Four short steps: install Python, create an environment, install MEEGqc, run it. Pick whichever Python and environment manager you already use; we show venv, conda, and uv.

Step 1. Install Python

MEEGqc needs Python 3.10 to 3.14. If python3 --version already prints a supported version, skip to Step 2.

Easiest: Homebrew.

brew install python@3.12

Or download the official installer from python.org/downloads/macos. Open the .pkg and follow the wizard.

Debian / Ubuntu:

sudo apt update
sudo apt install python3 python3-venv python3-pip

Fedora:

sudo dnf install python3 python3-pip

Arch:

sudo pacman -S python python-pip

If your distro ships Python older than 3.10, install pyenv and pull a newer build (pyenv install 3.12).

Easiest: winget.

winget install Python.Python.3.12

Or download the official installer from python.org/downloads/windows. When the installer opens, tick Add python.exe to PATH, then click Install Now.

Step 2. Create a virtual environment

MEEGqc pulls in MNE-Python, ancpBIDS, Plotly, PyQt6, NumPy, pandas, SciPy, Numba, joblib, and the rest of the dependency tree. Keep it in its own environment so it does not interfere with other projects.

The venv module ships with every Python 3.3+, so no extra install needed.

# create the environment
python3 -m venv ~/meegqc-env

# activate it (macOS / Linux)
source ~/meegqc-env/bin/activate

# activate it (Windows, PowerShell)
~/meegqc-env/Scripts/Activate.ps1

After activation your shell prompt is prefixed with (meegqc-env). Run deactivate when you're done.

If you already use Miniconda or Miniforge: 

# create + activate
conda create -n meegqc python=3.12 -y
conda activate meegqc

conda activate works in every shell (bash, zsh, fish, PowerShell, cmd) once conda has initialised your profile.

uv is a fast modern Python launcher. It manages Python versions and venvs in one tool. 

# create a venv pinned to Python 3.12
uv venv ~/meegqc-env --python 3.12

# activate it
source ~/meegqc-env/bin/activate

You can also skip the activation step and prefix every pip / python call with uv run.

Step 3. Install MEEGqc

With the environment active, either of these works:

# canonical, long-standing PyPI name (recommended for upgrades)
pip install meg-qc

# rebrand-aligned wrapper (pulls in meg-qc as its only dependency)
pip install meeg-qc

Two PyPI distributions ship in lockstep at the same version: meg-qc is the main package: every line of code lives here, existing users / CI pipelines / pinned requirements.txt files continue working unchanged. meeg-qc is a thin meta-package that declares meg-qc as its only dependency, so installing it pulls in the main wheel. End state is identical; the wrapper exists so new users can discover the tool under the current branding. The Python import name stays meg_qc either way (same pattern as pip install scikit-learn / import sklearn).

Step 4. Run MEEGqc

Launch the GUI:

meegqc

Or use the CLI directly. Each command ships with two interchangeable names. The rebrand-aligned meeg* form and the legacy meg* form. Both dispatch to the same Python function; use whichever you prefer.

Rebrand-aligned (new)Legacy (still works)What it does
meegqcmegqcLaunch the GUI.
run-meegqcrun-megqcCompute QA metrics for one or more BIDS datasets.
run-meegqc-plottingrun-megqc-plottingRender interactive HTML reports from existing derivatives.
get-meegqc-configget-megqc-configExport an editable settings.ini.
globalqualityindexRecompute the GQI from existing derivatives. No alias because the name has no megqc in it.
Re-activating later.

Every new shell session needs the environment activated again. For venv / uv: source ~/meegqc-env/bin/activate. For conda: conda activate meegqc.

Upgrading

pip install --upgrade meg-qc

Close the GUI first on Windows. Newer dependency pins may require recreating the venv if a pinned major version moves.

Reference

Check your architecture

The one-click installer ships pre-built binaries for specific CPU architectures (Apple Silicon on macOS, x86_64 on Linux and Windows). If you're not sure what your machine has, here's how to find out in under thirty seconds.

Option A. From the Apple menu.

  1. Click the Apple menu → About This Mac.
  2. Look at the Chip line.
    • "Apple M1 / M2 / M3 / M4...": Apple Silicon (arm64). Installer works.
    • "Intel Core...": Intel (x86_64). Use Method 2.

Option B. From the Terminal.

uname -m
  • arm64: Apple Silicon. Installer works.
  • x86_64: Intel Mac. Use Method 2.

Open a terminal and run:

uname -m
  • x86_64: 64-bit Intel / AMD. Installer works.
  • aarch64 / arm64: 64-bit ARM (e.g. Raspberry Pi 4/5, Apple Silicon under UTM). Use Method 2.
  • i686 / i386: 32-bit. Not supported (Python 3.10+ requires 64-bit).

Option A. From Settings.

  1. Open Settings → System → About.
  2. Look at the System type line.
    • "64-bit operating system, x64-based processor": x86_64. Installer works.
    • "... ARM-based processor": ARM Windows (Surface Pro X, etc.). Use Method 2.

Option B. From PowerShell.

echo $Env:PROCESSOR_ARCHITECTURE
  • AMD64: x86_64. Installer works.
  • ARM64: ARM. Use Method 2.
Troubleshooting

If something goes wrong

macOS: "unidentified developer" / app cannot be opened

Gatekeeper blocks unsigned scripts on first run. After the warning, open System Settings → Privacy & Security, scroll to Security, and click Open Anyway. Re-run the installer. One-time approval.

macOS: bootstrap installer on Intel Mac

The bundled macOS Python is arm64-only. On Intel Macs, use Method 2 (manual install) in a Python 3.10+ environment.

Linux: "could not load the Qt platform plugin xcb"

PyQt6 needs the system Qt platform library.

Debian / Ubuntu:

sudo apt install libxcb-cursor0 libxcb-xinerama0 libfontconfig1

Fedora:

sudo dnf install xcb-util-cursor fontconfig
Linux: Thunar refuses to run the script on double-click

By design. Run from a terminal, or enable script execution once with the xfconf-query command from the Linux tab above.

Windows: SmartScreen blocks the installer

Click More info → Run anyway. The installer is not code-signed yet, so SmartScreen flags any unknown publisher. Make sure the download came from the official GitHub release link.

Windows: update fails with "file in use"

Close MEEGqc fully before upgrading. A manual pip install --upgrade needs the app closed.

pip: "Could not find a version that satisfies the requirement"

Almost always a Python version mismatch. Run python --version in the active environment; you need 3.10, 3.11, 3.12, 3.13, or 3.14.

Any OS: install log

The bootstrap installer writes ~/MEEGqc/install.log. Paste it into a GitHub issue if you need help.

Next steps