Utilisation de fMRIPrep avec Docker et WSL2 sur Windows

Objectif

Ce tutoriel décrit pas à pas l’installation et l’utilisation de fMRIPrep avec Docker sous Windows, via le sous-système Linux WSL2. Il est basé sur un dataset téléchargé depuis OpenNeuro, et aborde également les erreurs courantes et leurs solutions.

1. Prérequis

• Windows 10 ou 11 avec WSL2 installé
• Docker Desktop installé et configuré avec WSL2
• Distribution Linux (ex. : Ubuntu-22.04)
• Python installé
• fMRIPrep installé avec :

python -m pip install --user fmriprep-docker

Et un dataset BIDS copié localement, par exemple : E:\tuto_SPM\ds004302

2. Ajouter fmriprep-docker au PATH

Ajoutez ce dossier au PATH utilisateur :

C:\Users\<NomUtilisateur>\AppData\Roaming\Python\Python311\Scripts

Étapes :

1. Ouvrir "Variables d’environnement" dans le menu Démarrer
2. Modifier la variable Path de l’utilisateur
3. Ajouter le chemin ci-dessus
4. Redémarrer le terminal

3. Configuration WSL2

Pour allouer plus de ressources à WSL2, créez un fichier .wslconfig dans C:\Users\<NomUtilisateur> :

[wsl2]
memory=8GB
processors=4
swap=2GB

Puis exécutez dans PowerShell :

wsl --shutdown

Relancez Docker Desktop ensuite.

4. Copie des données dans WSL

Dans Ubuntu (WSL), créez un dossier et copiez vos données :

mkdir -p ~/data/fmriprep
cp -r /mnt/e/tuto_SPM/ds004302 ~/data/fmriprep/
cp -r /mnt/e/tuto_SPM/freesurfer ~/data/fmriprep/
cp -r /mnt/e/tuto_SPM/fmriprep_output ~/data/fmriprep/

5. Commande fMRIPrep

À lancer dans PowerShell (en version UNC Windows) :

fmriprep-docker \\wsl.localhost\Ubuntu-22.04\home\maxidieu\data\fmriprep\ds004302 \
                 \\wsl.localhost\Ubuntu-22.04\home\maxidieu\data\fmriprep\fmriprep_output \
                 participant \
                 --fs-license-file \\wsl.localhost\Ubuntu-22.04\home\maxidieu\data\fmriprep\freesurfer\license.txt \
                 --fs-subjects-dir \\wsl.localhost\Ubuntu-22.04\home\maxidieu\data\fmriprep\freesurfer \
                 --participant-label 01

6. Problèmes rencontrés et solutions

Erreur 1 : <8GB RAM available

Solution : Vérifiez votre fichier .wslconfig.

Erreur 2 : dataset_description.json missing

cp /mnt/e/tuto_SPM/ds004302/dataset_description.json ~/data/fmriprep/ds004302/

Erreur 3 : RepetitionTime must be defined

Copier le fichier task-speech_bold.json :

cp /mnt/e/tuto_SPM/ds004302/task-speech_bold.json ~/data/fmriprep/ds004302/

{
  "RepetitionTime": 2
}

Erreur 4 : ln: failed to create symbolic link

Cause : les volumes montés depuis Windows ne permettent pas les symlinks nécessaires à FreeSurfer.

Solution : Tout stocker directement dans WSL (pas dans /mnt/).

7. Remarques

• Les chemins WSL doivent commencer par \\wsl.localhost\...
• Assurez-vous que Docker Desktop est bien lancé
• Validez votre dataset BIDS avant exécution

8. Annexes

Exemple de task-speech_bold.json

{
  "TaskName": "speech",
  "RepetitionTime": 2.0,
  "Manufacturer": "Philips"
}

Document rédigé le 17 mai 2025