Neuroimaging CLI tools, one web page at a time.
NeuroFlow is a facilitation portal for neuroscience medical image processing: one independent page per CLI (FreeSurfer, FSL, and Spinal Cord Toolbox in the portal today). Each module provides upload, parameter forms, command preview, and local subprocess execution.
It is not a multi-tool pipeline runner and does not ship Docker. The release is the portal only — it does not install FreeSurfer, FSL, or SCT, and there is no login. You install host packages yourself; NeuroFlow wraps them in a FastAPI + HTML/Tailwind UI.
Stack: Python 3.10+ · Poetry · FastAPI · HTML/Tailwind · pytest · MkDocs
Versioning: Semantic Versioning (MAJOR.MINOR.PATCH), starting at 0.0.1. Merges to main drive releases via Conventional Commits (see CHANGELOG.md).
Docs: User guide on Read the Docs · in-app help at /help/ · OpenAPI at /docs
- I only want to use NeuroFlow — download a zip from GitHub Releases. No git, Poetry, or Node.
- I want to develop NeuroFlow — clone the repo on Ubuntu/Debian and run from source.
Full walkthroughs: Installation · Windows and WSL · Development
Download the asset for your OS from the latest GitHub Release. Extract the archive and keep the folder intact (_internal/ must stay next to the binary; on Windows also keep linux-payload/).
The app starts the local API, serves the UI, and opens http://127.0.0.1:8000/. Job and dataset files live under ~/.neuroflow/ in the environment where the portal runs (Ubuntu home on Windows via WSL — not under C:\Users\... as the primary store).
- Download
neuroflow-*-linux-*.zipand extract it. - Make the binary executable:
chmod +x neuroflow/neuroflow - Run:
./neuroflow/neuroflow - A browser should open at http://127.0.0.1:8000/. Leave the terminal open while you use the portal.
- Stop with Ctrl+C in that terminal.
Data: ~/.neuroflow/jobs and ~/.neuroflow/datasets.
- Download
neuroflow-*-macos-*.zipand extract it. - Run:
./neuroflow/neuroflow - If Gatekeeper blocks the binary, use System Settings → Privacy & Security → Open Anyway, or after extract:
xattr -dr com.apple.quarantine neuroflow - A browser should open at http://127.0.0.1:8000/. Leave the terminal open while you use the portal.
- Stop with Ctrl+C in that terminal.
Install FreeSurfer, FSL, and SCT as native macOS packages where vendors support them.
On Windows you click NeuroFlow, use the site in Chrome, and processing happens in Linux on WSL — if WSL and the neuroimaging tools are already installed. NeuroFlow points you to official docs; it does not install WSL or vendor CLIs.
Requirements: Windows 11 + WSL2 (primary; Windows 10 + WSL2 works with possible localhost caveats), distro name Ubuntu, x86_64 only (ARM is refused).
- Install WSL2 + Ubuntu yourself via Microsoft’s WSL guide. NeuroFlow never runs
wsl --install, never reboots your PC, and never enables Windows features for you. - Open Ubuntu once and create a Linux username and password (not your Windows account).
- Download
neuroflow-*-windows-x86_64.zipand extract it. KeepNeuroFlow.exe,_internal/, andlinux-payload/together. - Double-click
NeuroFlow.exe. - If WSL or Ubuntu is missing, follow the on-screen Microsoft link, finish Ubuntu setup, then click again.
- If SmartScreen warns (“Windows protected your PC”), choose More info → Run anyway when you trust the release source.
- Stop the portal later with:
NeuroFlow.exe --stop(does not shut down WSL; does not cancel running jobs).
Full path: Windows and WSL on Read the Docs.
The release zip does not include FreeSurfer, FSL, or SCT.
| Platform | Where to install tools |
|---|---|
| Linux / macOS | On that machine (PATH or NEUROFLOW_* env overrides) |
| Windows | Inside WSL2 Ubuntu, not on the native Windows PATH |
If Home shows Install on host, the probe failed on the OS where the portal runs (Ubuntu on Windows). Install the package, then rescan — see Host tools.
Development and from-source install target Ubuntu 22.04+ / Debian 12+ with Poetry:
git clone https://github.com/acsenrafilho/neuroflow.git
cd neuroflow
make setup
make apiOpen http://127.0.0.1:8000/ (with NEUROFLOW_SERVE_FRONTEND=1 from .env.example).
Full from-source setup, desktop shortcut, frontend preview, and make targets: Development · CONTRIBUTING.md.
neuroflow/ # Python package (api, tools, services)
frontend/ # Production UI (hub + per-tool pages)
packaging/ # Desktop entry + PyInstaller release build
doc/mockup/ # Legacy design reference mockups
doc/licenses/ # Third-party tool license notices
data/jobs/ # Job metadata and logs (gitignored contents)
data/datasets/ # BIDS-inspired workspace / subject trees
docs/ # MkDocs source
scripts/ # setup, launch, host scan helpers
tests/
- User documentation: https://neuroflowpipelines.readthedocs.io/
- In-app user guide: http://127.0.0.1:8000/help/ (when the frontend is served)
- OpenAPI (Swagger): http://127.0.0.1:8000/docs
- Health:
GET /api/v1/health
See CONTRIBUTING.md. Short path:
- Register the tool in
neuroflow/tools/registry.py. - Add argv builder + launcher under
neuroflow/tools/<name>.py. - Add API routes under
neuroflow/api/v1/tools.py(or a dedicated router). - Add
frontend/src/pages/tools/<name>.htmlfollowing the FreeSurfer module pattern.
NeuroFlow is a personal project. Issues and pull requests are welcome; response time may vary.
- Open an issue for bugs, features, or questions (use the form that matches).
- Look for
good first issueandhelp wanted. - Read CONTRIBUTING.md and the Code of Conduct.
- Security reports: SECURITY.md (private advisory, not a public issue).
If you use NeuroFlow in academic work, cite the software via CITATION.cff (GitHub Cite this repository).
Optional GitHub Sponsors support maintenance time. The software remains MIT-licensed either way.
MIT — see LICENSE. Third-party neuroimaging tools (FSL, ANTs, FreeSurfer, 3D Slicer) have separate licenses; see doc/licenses/.