Unsloth sur Docker : installation facile sous Linux et Windows 11 (WSL2)

Installer Unsloth peut sembler intimidant, surtout quand on débute avec l’entraînement de modèles IA et l’usage intensif des GPU. Avec Docker et docker-compose, le déploiement devient bien plus simple, reproductible et facile à maintenir, que vous soyez sous Linux natif ou sous Windows 11 avec WSL2. C’est la méthode que je vous recommande pour ne pas perdre de temps avec des problèmes de dépendances et gagner également en maintenabilité.

Dans cet article, nous allons détailler pas à pas l’installation d’Unsloth sur Docker, en particulier pour les GPU NVIDIA Blackwell comme la RTX 5090. Nous utiliserons un fichier docker-compose.yml afin de centraliser la configuration. Cela permet d’éviter les erreurs de commande répétitives et de garantir que vous ou vos collaborateurs puissiez reproduire exactement le même environnement à tout moment.

Les informations et bonnes pratiques présentées s’appuient sur la documentation officielle Unsloth, la page de l’image unsloth/unsloth-blackwell sur Docker Hub ainsi que le dépôt GitHub Unsloth.

---

Pourquoi choisir Docker pour Unsloth ?

Installer Unsloth directement dans votre système peut rapidement devenir complexe : versions de CUDA à gérer, dépendances spécifiques, compatibilité avec PyTorch… Docker règle ce problème en encapsulant tout dans une image. Vous téléchargez, lancez et c’est prêt.

Avec docker-compose, l’avantage est encore plus net :

• Simplicité : toutes les options (volumes, ports, GPU) sont décrites une fois dans un fichier YAML.
• Maintenance réduite : une mise à jour de l’image se fait avec une seule commande.
• Reproductibilité : vous pouvez partager le fichier docker-compose.yml sur vos différents postes de travail, serveurs ou avec vos collègues, ils auront exactement la même configuration.
• Compatibilité : les images unsloth/unsloth-blackwell sont spécialement pensées pour les GPU RTX de génération Blackwell. Il existe également une image docker pour les générations précédente disponible sur Docker Hub.

---

Pré-requis pour Linux et Windows 11 (WSL2)

Avant de démarrer, assurez-vous d’avoir :

• Un GPU NVIDIA compatible Blackwell (par ex. RTX 5090) avec drivers à jour.
• Docker installé (sous Linux natif ou dans WSL2).
• Le NVIDIA Container Toolkit configuré correctement pour permettre à Docker d’accéder au GPU. S’il n’est pas déjà installé, suivez ce guide. Vérifier également la version nécessaire dans la documentation Unsloth. La version peut changer, je ne la mentionne donc pas ici.

---

Exemple de fichier docker-compose.yml

Voici un exemple complet pour déployer Unsloth avec Docker Compose à déposer dans votre répertoire, par exemple /srv/unsloth :

services:
  unsloth:
    # pour les GPU avant la génration blackwell: unsloth/unsloth:stable
    image: unsloth/unsloth-blackwell:stable
    container_name: unsloth-blackwell
    # GPU
    gpus: all
    # Mémoire RAM partagée (datasets + loaders rapides) à adapter en fonction de votre configuration
    shm_size: "32g"
    ipc: host
    # Répertoire de travail dans le conteneur
    working_dir: /workspace
    environment:
      - TZ=Europe/Paris
      # Caches et modèles Hugging Face / Torch
      - HF_HOME=/data/hf
      - HUGGINGFACE_HUB_CACHE=/data/hf
      - TRANSFORMERS_CACHE=/data/hf
      - TORCH_HOME=/data/torch
      - JUPYTER_PASSWORD=pwdjupyter
      - USER_PASSWORD=pwdunsloth
    volumes:
      # Code, scripts, notebooks
      - ./workspace:/workspace
      # Caches modèles/tokenizers (persistants)
      - ./data/hf:/data/hf
      - ./data/torch:/data/torch
      # Jeux de données en lecture
      - ./data/datasets:/datasets
      # Poids de checkpoints et sorties
      - ./data/checkpoints:/checkpoints
      - ./outputs:/outputs
    # Ouvre un shell par défaut; remplace par ta commande d’entraînement
    command: bash
    # Optionnel: si tu lances un notebook à l’intérieur
    ports:
       - "8888:8888"

Explication des volumes

• ./workspace : scripts, notebooks, code utilisateur.
• ./data/hf et ./data/torch : caches Hugging Face et Torch, pour éviter de retélécharger les modèles.
• ./data/datasets : vos jeux de données en lecture.
• ./data/checkpoints : stockage des checkpoints d’entraînement.
• ./outputs : logs, métriques et exports.

Avec cette structure, tout est persistant sur votre machine hôte, même si vous supprimez ou recréez le conteneur.

---

Lancer le conteneur

1. Créez les répertoires nécessaires :

mkdir -p workspace data/hf data/torch data/datasets data/checkpoints outputs

2. Lancez le conteneur :

docker compose up -d

3. Vérifiez qu’il tourne :

docker ps

Vous devriez voir unsloth-blackwell avec le port 0.0.0.0:8888->8888/tcp.

---

Accéder à Jupyter Notebook

Ouvrez votre navigateur et allez sur : http://localhost:8888

Un écran de connexion apparaît. Entrez le mot de passe que vous avez défini dans votre fichier docker-compose.yml via la variable JUPYTER_PASSWORD.

Vous voilà dans l’interface Jupyter Notebook intégrée à Unsloth. Vous pouvez commencer avec les notebooks fournis par l’équipe (voir la section Fine-tuning Guide dans la documentation Unsloth).

---

Accéder au terminal du conteneur

Pour certaines opérations (installation de paquets, exploration de fichiers, lancement de scripts), l’accès en ligne de commande est souvent plus efficace que l’interface Jupyter.

Pas besoin de SSH en local :

docker compose exec unsloth bash

Vous ouvrez ainsi un shell Bash directement dans le conteneur, avec accès à /workspace, /datasets et vos volumes montés.

---

Points à vérifier et améliorations possibles

• Compatibilité CUDA / drivers : selon la version des drivers Windows et du NVIDIA Container Toolkit, il peut y avoir des décalages. [À vérifier selon votre configuration locale].
• Ressources GPU : l’exemple utilise gpus: all, mais vous pouvez limiter à un GPU spécifique si vous en avez plusieurs.
• Sécurité : en usage local ce n’est pas critique, mais si vous exposez le port 8888 sur un réseau, définissez toujours un JUPYTER_PASSWORD fort, et un reverse proxy sécurisé.
• Performances : le paramètre shm_size: « 32g » est important pour les DataLoader PyTorch. Ajustez-le si votre hôte a moins de RAM disponible.

---

Problèmes de droits et solutions possibles

Lors de l’installation d’Unsloth via Docker, il est courant de rencontrer des erreurs du type Permission denied dans Jupyter Notebook au moment de créer un fichier (ex. untitled.txt). Ce problème est lié au fait que l’image Unsloth ne tourne pas en root par défaut, mais avec un utilisateur non-root appelé unsloth (UID 1000, GID 1000). Si vos répertoires montés (workspace, data, outputs) appartiennent à un autre utilisateur, unsloth ne peut pas écrire dedans.

Symptômes fréquents

• Impossible de créer un nouveau fichier depuis Jupyter (Permission denied).
• Impossibilité d’enregistrer des checkpoints ou des logs dans /checkpoints ou /outputs.

Solutions possibles

1. Adapter les droits en mode rapide
   Pour un usage local (Linux ou WSL2), vous pouvez accorder tous les droits aux répertoires :

sudo chmod -R 777 workspace data outputs

C’est efficace, mais cela donne un accès total à tous les utilisateurs du système. Acceptable en local, non recommandé en production.

2. Attribuer les dossiers à l’utilisateur unsloth
   La méthode la plus propre consiste à changer le propriétaire des répertoires montés pour qu’ils correspondent à l’UID/GID de l’utilisateur unsloth :

sudo chown -R 1000:1000 workspace data outputs

Ainsi, l’utilisateur à l’intérieur du conteneur a exactement les droits nécessaires.

3. Utiliser USER_PASSWORD pour sudo dans le conteneur
   Si vous devez parfois exécuter des commandes administratives à l’intérieur du conteneur, définissez dans le docker-compose.yml :

environment:
  - USER_PASSWORD=monmotdepasseuser

Cela vous permet d’utiliser sudo avec le mot de passe défini, tout en gardant Jupyter et vos scripts exécutés sous l’utilisateur unsloth.

4. Volumes en lecture seule pour certaines données
   Si vous avez des dossiers qui ne doivent pas être modifiés (par exemple datasets), vous pouvez les monter en lecture seule dans docker-compose.yml :

- ./data/datasets:/datasets:ro

Bonnes pratiques

• Pour un environnement local de développement : chmod 777 est la solution la plus simple.
• Pour un environnement partagé ou en production : privilégiez chown 1000:1000 et des volumes :ro pour les jeux de données.
• Toujours définir JUPYTER_PASSWORD et éventuellement USER_PASSWORD pour garder un minimum de sécurité et éviter les blocages.

Ces ajustements garantissent que vos notebooks, checkpoints et exports fonctionneront sans erreurs dans Unsloth, que vous soyez sous Linux ou WSL2.

---

Conclusion

Grâce à Docker et docker-compose, l’installation d’Unsloth sur Linux et Windows 11 via WSL2 est largement simplifiée. Plus besoin de jongler avec CUDA ou PyTorch manuellement : l’image officielle unsloth/unsloth-blackwell:stable contient déjà tout ce qu’il faut pour exploiter votre GPU Blackwell.

Avec un simple docker compose up -d, vous disposez d’un environnement reproductible, prêt à lancer vos notebooks et vos scripts d’entraînement IA.

Pour aller plus loin, explorez le dépôt GitHub Unsloth pour trouver des exemples avancés, ou suivez les guides de la documentation officielle.

---