Installation

Installation is easy.

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

Whichever you pick, there is nothing else to install afterwards. Every engine BIDS Manager uses is installed with it.

For	Engine	You install it
MRI DICOM to NIfTI	dcm2niix	Included, program and all
EEG and MEG	mne-bids	Included
PET DICOM, ECAT and blood	pet2bids	Included
MRI physiological recordings	bidsphysio	Built in
Defacing, and the atlas skull strip	niimath	Included, program and all
The neural skull strip	brainchop, running mindgrab	Included
Naming and validation	The BIDS schema and validator	Built in

You do not need Python installed beforehand if you use the one-click installer: it brings its own. Nothing is installed system-wide, and removing BIDS Manager means deleting a single folder.

If you are installing into a Python you already have, 3.10 to 3.14 inclusive are supported. Anything outside that range will refuse to install rather than half work.

One gap, and it is upstream: niimath publishes a wheel per Python version and does not have one for 3.14 yet. On Python 3.14 BIDS Manager installs and runs normally: the Deface entry is greyed out with a tooltip saying why, and the skull-stripping dialog opens with its Run button disabled and the same explanation on it. Every Python version from 3.10 to 3.13 has the wheel. The one-click installer brings its own Python, so this affects only a pip install into a 3.14 environment.

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)

Set up an environment with uv, venv or conda, then install bids-manager into it. Useful if you already manage Python environments or want to keep everything inside your existing toolchain. With uv you do not need a system Python at all: it fetches one for you.

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 BIDS Manager 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.

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

Prefer the terminal?

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

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

Open a terminal in the Linux/ folder.
Make the script executable.
```
chmod +x install_BIDS_Manager.sh
```
Run it.
```
./install_BIDS_Manager.sh
```
Launch BIDS Manager from your application menu. That entry runs the bundled launcher, which sources the venv for you.

Using the terminal on Linux.

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

source ~/BIDS-Manager/env/bin/activate
bidsmgr

Same applies to the bidsmgr-scan / bidsmgr-convert / bidsmgr-validate CLI verbs. If you want them always on PATH, append the line above to your ~/.bashrc / ~/.zshrc or symlink ~/BIDS-Manager/env/bin/bidsmgr 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 BIDS Manager icon.

Inside the Windows/ folder, double-click install_BIDS_Manager.bat.
If SmartScreen shows Windows protected your PC, click More info → Run anyway.
A console opens and the install runs. A BIDS-Manager shortcut appears on your Desktop and in the Start Menu when finished.
Double-click the Desktop shortcut to launch.

First launch is slower.

The first start pre-compiles the embedded Python and caches the BIDS schema. 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 ~/BIDS-Manager/.

Hover a step to preview, click to pin.

After install

Launch, uninstall, where things land

The BIDS Manager Home tab after a fresh install — **What a working install looks like.** BIDS Manager opens on the Home tab, where you create a dataset project or open one you already have. If you see this, every conversion engine came with it and there is nothing else to install.

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

Where things are installed

OS	Install root
macOS	`/Users/<you>/BIDS-Manager/`
Linux	`/home/<you>/BIDS-Manager/`
Windows	`C:\Users\<you>\BIDS-Manager\`

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

Method 2 . Manual (CLI)

Install into your own Python environment

Pick your system, then the tool you want to hold the environment, and follow the four commands underneath. Each combination is written out in full, so there is nothing to translate from another platform.

BIDS Manager needs Python 3.10 to 3.14. Where that Python comes from depends on the tool: uv and conda both fetch one, venv uses the one you already have.

Everything below is run in Terminal. Pick the tool you want to hold the environment:

uv fetches the Python version you ask for, so there is nothing else to install.

1. Install uv

With Homebrew:

brew install uv

Without Homebrew. The official installer needs nothing installed first (curl ships with macOS) and puts uv in ~/.local/bin:

curl -LsSf https://astral.sh/uv/install.sh | sh

Open a new terminal afterwards so uv is on your PATH, then check it with uv --version. Every other way to install it is listed in the uv installation guide.

2. Create the environment and activate it

uv venv ~/bidsmgr-env --python 3.12
source ~/bidsmgr-env/bin/activate

3. Install BIDS Manager

uv pip install bids-manager

uv pip, not pip: uv installs packages itself, so this environment has no pip of its own.

4. Run it

bidsmgr

venv ships with Python and wraps the one you already have, so that one has to be a supported version.

1. Check your Python

python3 --version

You need 3.10 to 3.14. If it is older, or the command is not found, install one with brew install python@3.12 (Homebrew), or download the installer from python.org, which needs no package manager.

2. Create the environment and activate it

python3 -m venv ~/bidsmgr-env
source ~/bidsmgr-env/bin/activate

3. Install BIDS Manager

pip install bids-manager

4. Run it

bidsmgr

conda brings its own Python, so there is nothing else to install.

1. Install Miniforge

Skip this if you already have conda. With Homebrew:

brew install --cask miniforge

Without Homebrew:

URL=https://github.com/conda-forge/miniforge/releases/latest/download
curl -L -O "$URL/Miniforge3-$(uname)-$(uname -m).sh"
bash Miniforge3-$(uname)-$(uname -m).sh

Run conda init once afterwards, then open a new terminal. Every build is listed on the Miniforge releases page.

2. Create the environment and activate it

conda create -n bidsmgr python=3.12 -y
conda activate bidsmgr

3. Install BIDS Manager

pip install bids-manager

4. Run it

bidsmgr

Everything below is run in your terminal. Pick the tool you want to hold the environment:

uv fetches the Python version you ask for, so there is nothing else to install.

1. Install uv

The official installer works on every distribution and needs nothing installed first. It puts uv in ~/.local/bin:

curl -LsSf https://astral.sh/uv/install.sh | sh

If curl is not installed, the same script through wget:

wget -qO- https://astral.sh/uv/install.sh | sh

Or with pipx, if you already use it:

pipx install uv

Open a new terminal afterwards so uv is on your PATH, then check it with uv --version. Your distribution may also package uv; the uv installation guide lists what is available.

2. Create the environment and activate it

uv venv ~/bidsmgr-env --python 3.12
source ~/bidsmgr-env/bin/activate

3. Install BIDS Manager

uv pip install bids-manager

uv pip, not pip: uv installs packages itself, so this environment has no pip of its own.

4. Run it

bidsmgr

venv ships with Python and wraps the one you already have, so that one has to be a supported version.

1. Check your Python

python3 --version

You need 3.10 to 3.14. On Debian or Ubuntu install one with sudo apt install python3 python3-venv python3-pip; Fedora uses dnf, Arch uses pacman. If your distribution only ships something older, use pyenv, or switch to the uv tab, which fetches a Python without building one.

2. Create the environment and activate it

python3 -m venv ~/bidsmgr-env
source ~/bidsmgr-env/bin/activate

3. Install BIDS Manager

pip install bids-manager

4. Run it

bidsmgr

conda brings its own Python, so there is nothing else to install.

1. Install Miniforge

Skip this if you already have conda:

URL=https://github.com/conda-forge/miniforge/releases/latest/download
curl -L -O "$URL/Miniforge3-$(uname)-$(uname -m).sh"
bash Miniforge3-$(uname)-$(uname -m).sh

Run conda init once afterwards, then open a new terminal. Every build is listed on the Miniforge releases page.

2. Create the environment and activate it

conda create -n bidsmgr python=3.12 -y
conda activate bidsmgr

3. Install BIDS Manager

pip install bids-manager

4. Run it

bidsmgr

Everything below is run in PowerShell. Pick the tool you want to hold the environment:

uv fetches the Python version you ask for, so there is nothing else to install.

1. Install uv

With winget, which ships with Windows 10 and 11:

winget install --id=astral-sh.uv -e

Without winget. The official installer needs nothing installed first:

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Open a new PowerShell window afterwards so uv is on your PATH, then check it with uv --version. Every other way to install it is listed in the uv installation guide.

2. Create the environment and activate it

uv venv $HOME\bidsmgr-env --python 3.12
$HOME\bidsmgr-env\Scripts\Activate.ps1

3. Install BIDS Manager

uv pip install bids-manager

uv pip, not pip: uv installs packages itself, so this environment has no pip of its own.

4. Run it

bidsmgr

venv ships with Python and wraps the one you already have, so that one has to be a supported version.

1. Check your Python

python --version

You need 3.10 to 3.14. If it is older, or the command is not found, install one with winget install Python.Python.3.12 (winget), or download the installer from python.org and tick Add python.exe to PATH.

2. Create the environment and activate it

python -m venv $HOME\bidsmgr-env
$HOME\bidsmgr-env\Scripts\Activate.ps1

3. Install BIDS Manager

pip install bids-manager

4. Run it

bidsmgr

conda brings its own Python, so there is nothing else to install.

1. Install Miniforge

Skip this if you already have conda. With winget, which ships with Windows 10 and 11:

winget install --id=CondaForge.Miniforge3 -e

Without winget, download Miniforge3-Windows-x86_64.exe from the Miniforge releases page and double-click it: that one is a normal Windows installer, not a command. Either way, use the Miniforge Prompt from the Start menu afterwards, or run conda init powershell once to use PowerShell instead.

2. Create the environment and activate it

conda create -n bidsmgr python=3.12 -y
conda activate bidsmgr

3. Install BIDS Manager

pip install bids-manager

4. Run it

bidsmgr

Re-activating later.

Every new shell session needs the environment activated again. That is the second line of step 2 on your tab, on its own: source ~/bidsmgr-env/bin/activate for uv and venv on macOS and Linux, $HOME\bidsmgr-env\Scripts\Activate.ps1 in PowerShell, and conda activate bidsmgr for conda on any system.

About the package

The package on PyPI is named bids-manager. The Python import name is bidsmgr (same pattern as pip install scikit-learn / import sklearn). PyPI page.

The command line

Or use the CLI directly. Eight commands are installed:

bidsmgr. The graphical interface, with the Converter and the Editor in one window.
bidsmgr-create. Scaffold a new BIDS dataset and start a project in it.
bidsmgr-project. List the scan versions saved in a project.
bidsmgr-scan. Walk a raw folder and produce a 62-column inventory TSV.
bidsmgr-rebuild. Re-derive BIDS names from the TSV after manual edits.
bidsmgr-convert. Convert the rows in the TSV into the BIDS dataset.
bidsmgr-metadata. Post-conversion metadata: the template answers, field-maps, IntendedFor and scans.tsv.
bidsmgr-validate. Schema-driven validation, with the rule behind every finding.

Upgrading

With the environment active. uv:

uv pip install --upgrade bids-manager

venv and conda:

pip install --upgrade bids-manager

Close the GUI first on Windows. Newer dependency pins may require recreating the environment 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.

Click the Apple menu → About This Mac.
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.

Open Settings → System → About.
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 BIDS Manager fully before upgrading. From v1.0.2 the in-GUI updater spawns a detached helper, but a manual pip install --upgrade still 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 ~/BIDS-Manager/install.log. Paste it into a GitHub issue if you need help.

Next steps

Walk the interactive tutorial. Scan, inspect, convert, edit, validate, all simulated in the browser.
See the workflow: eight stages, three lenses, one schema-driven engine.
Read the architecture write-up for the engine internals.