Installation

Installation is easy.

Two methods, both supported, both lead to the same working BIDS Manager. 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 bids-manager. 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 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.

  1. Double-click install_BIDS_Manager.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 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.

  1. Open a terminal in the Linux/ folder.
  2. Make the script executable. 
    chmod +x install_BIDS_Manager.sh
  3. Run it. 
    ./install_BIDS_Manager.sh
  4. 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.

  1. Inside the Windows/ folder, double-click install_BIDS_Manager.bat.
  2. If SmartScreen shows Windows protected your PC, click More info → Run anyway.
  3. A console opens and the install runs. A BIDS-Manager 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 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

OSLaunchUninstall
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

OSInstall 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 with pip in your own environment

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

Step 1. Install Python

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

BIDS Manager pulls in PyQt6, mne-bids, dcm2niix, pydicom, bidsschematools, and the rest of the dependency tree. Keep it in its own environment so it doesn't interfere with other projects.

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

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

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

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

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

If you already use Miniconda or Miniforge: 

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

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 ~/bidsmgr-env --python 3.12

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

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

Step 3. Install BIDS Manager

With the environment active: 

pip install bids-manager

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.

Step 4. Run BIDS Manager

Launch the GUI:

bidsmgr

Or use the CLI directly. Six commands are installed:

  • bidsmgr. GUI (Converter and Editor in one window).
  • bidsmgr-scan. Walk a raw folder and produce a 51-column inventory TSV.
  • bidsmgr-rebuild. Re-derive BIDS names from the TSV after manual edits.
  • bidsmgr-convert. Run the conversion to BIDS for the rows in the TSV.
  • bidsmgr-metadata. Post-conversion metadata fix-ups (field-maps, IntendedFor, scans.tsv).
  • bidsmgr-validate. Two-layer validation: BIDS Manager's schema audit plus bidsschematools.
Re-activating later.

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

Upgrading

pip install --upgrade bids-manager

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