> For the complete documentation index, see [llms.txt](https://unsloth.ai/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://unsloth.ai/docs/fr/commencer/install/docker.md).
# Installer Unsloth via Docker
Installez Unsloth à l'aide de notre conteneur Docker officiel
Découvrez comment exécuter et entraîner des modèles avec le conteneur Docker Unsloth. Aucune configuration requise : toutes les dépendances sont préinstallées. Il vous suffit de récupérer l’image et de commencer à exécuter et entraîner des modèles sur vos GPU NVIDIA ou AMD locaux.
| **NVIDIA** Docker : [**`unsloth/unsloth`**](https://hub.docker.com/r/unsloth/unsloth) | **AMD** Docker : [**`unsloth/unsloth-rocm`**](https://hub.docker.com/r/unsloth/unsloth-rocm) |
| ------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
{% hint style="success" %}
**NOUVEAU sept. 2026 : le conteneur Docker Unsloth est désormais mis à jour avec Unsloth Studio et AMD.**
Unsloth partage le même cache que les notebooks et les scripts afin d’éviter des re-téléchargements inutiles.
{% endhint %}
### Démarrage rapide
Cette section du guide s’applique aux systèmes dotés de GPU NVIDIA. Si vous avez [AMD, voir ici](#amd-quickstart).
{% tabs %}
{% tab title="Linux / WSL" %}
Pour obtenir Docker d’Unsloth sur des GPU NVIDIA, exécutez ce qui suit dans le terminal :
```bash
docker run -d --name unsloth --gpus all --ipc=host \
--ulimit memlock=-1 --ulimit stack=67108864 \
-p 8000:8000 -p 8888:8888 \
-e JUPYTER_PASSWORD="mypassword" \
-v "$PWD":/workspace/host \
-v "$HOME/.cache/huggingface":/workspace/.cache/huggingface \
-v unsloth-studio:/opt/unsloth-studio \
unsloth/unsloth
```
* Exécutez-le depuis le dossier de votre projet, car ce dossier (`$PWD`) devient `/workspace/host`.
* Ce que font les indicateurs : exposition des ports 8000 (Unsloth Studio) et 8888 (JupyterLab) ; les trois `-v` indicateurs conservent vos fichiers, modèles et données Unsloth Studio.
* Exigence : pilote NVIDIA 570.26 ou plus récent.
{% endtab %}
{% tab title="Windows (PowerShell)" %}
Exécutez ce qui suit dans PowerShell :
```powershell
docker run -d --name unsloth --gpus all --ipc=host `
--ulimit memlock=-1 --ulimit stack=67108864 `
-p 8000:8000 -p 8888:8888 `
-e JUPYTER_PASSWORD="mypassword" `
-v "${PWD}:/workspace/host" `
-v "${HOME}/.cache/huggingface:/workspace/.cache/huggingface" `
-v "unsloth-studio:/opt/unsloth-studio" `
unsloth/unsloth
```
* Exécutez-le depuis le dossier de votre projet, car ce dossier (`${PWD}`) devient `/workspace/host`.
* Ce que font les indicateurs : exposition des ports 8000 (Unsloth Studio) et 8888 (JupyterLab) ; les trois `-v` indicateurs conservent vos fichiers, modèles et données Unsloth Studio.
* Exigence : pilote NVIDIA 570.26 ou plus récent.
{% endtab %}
{% endtabs %}
### Prérequis
Si Docker et NVIDIA Container Toolkit ne sont pas installés, suivez les instructions ci-dessous :
{% tabs %}
{% tab title="Linux / WSL" %}
Installez [Docker Engine](https://docs.docker.com/engine/install/) ou [Docker Desktop](https://docs.docker.com/desktop/), si ce n’est pas déjà fait :
```bash
curl -fsSL https://get.docker.com -o get-docker.sh && sh get-docker.sh
```
Si vous avez un GPU NVIDIA, installez [NVIDIA Container Toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html#installation) si ce n’est pas déjà fait :
```bash
curl -fsSL https://raw.githubusercontent.com/unslothai/unsloth/main/docker/install_nvidia_toolkit.sh -o install_nvidia_toolkit.sh && sudo -E bash install_nvidia_toolkit.sh
```
{% endtab %}
{% tab title="Windows" %}
**Installez Docker Desktop et le pilote NVIDIA.**
Installez [Docker Desktop pour Windows](https://docs.docker.com/desktop/setup/install/windows-install/) et le plus récent [pilote NVIDIA pour Windows](https://www.nvidia.com/Download/index.aspx). \
Puis mettez à jour WSL dans PowerShell :
```powershell
wsl --update
```
Dans les paramètres de Docker Desktop, sélectionnez **Général** et vérifiez que **Use the WSL 2 based engine** est activé. Attendez que le moteur démarre avant de continuer.
Aucune installation séparée de NVIDIA Container Toolkit n’est nécessaire. [Dépannage GPU Windows](https://docs.docker.com/desktop/features/gpu/).
{% endtab %}
{% endtabs %}
### Démarrage rapide AMD
Cette section du guide s’applique aux systèmes dotés de GPU AMD. Si vous avez [NVIDIA, voir ici](#quickstart).
{% tabs %}
{% tab title="Linux" %}
Pour obtenir Docker d’Unsloth sur des GPU AMD, exécutez ce qui suit dans le terminal :
```bash
GPU_FLAGS="--device /dev/kfd"
[ -e /dev/dri ] && GPU_FLAGS="$GPU_FLAGS --device /dev/dri"
for g in video render; do
gid=$(getent group "$g" | cut -d: -f3)
[ -n "$gid" ] && GPU_FLAGS="$GPU_FLAGS --group-add $gid"
done
docker run -d --name unsloth \
$GPU_FLAGS \
--ipc=host \
--ulimit memlock=-1 --ulimit stack=67108864 \
-p 8000:8000 -p 8888:8888 \
-e JUPYTER_PASSWORD="mypassword" \
-v "$PWD":/workspace/host \
-v "$HOME/.cache/huggingface":/workspace/.cache/huggingface \
-v unsloth-studio:/opt/unsloth-studio \
unsloth/unsloth-rocm
```
* Exécutez-le depuis le dossier de votre projet, car ce dossier (`$PWD`) devient `/workspace/host`.
* Ce que font les indicateurs : `$GPU_FLAGS` transmet les nœuds de périphérique GPU et les identifiants de groupe ; les ports 8000 (Unsloth Studio) et 8888 (JupyterLab) ; les trois `-v` indicateurs conservent vos fichiers, modèles et données Unsloth Studio.
* Exigence : un pilote `amdgpu` fonctionnel. Compilé avec ROCm 7.2, prend en charge RDNA1 et les versions plus récentes, ainsi que CDNA.
{% endtab %}
{% tab title="WSL" %}
Dans WSL, les GPU AMD sont accessibles via le pont DXG de WSL2. Exécutez ceci à l’intérieur de votre distribution WSL2, pas dans PowerShell, WSL2 n’a pas `/dev/kfd` donc le GPU est transmis comme `/dev/dxg` à la place :
```bash
docker run -d --name unsloth --device /dev/dxg --ipc=host \
--ulimit memlock=-1 --ulimit stack=67108864 \
-e HSA_ENABLE_DXG_DETECTION=1 \
-e LD_LIBRARY_PATH=/usr/lib/wsl/lib:/opt/rocm/lib \
-p 8000:8000 -p 8888:8888 \
-e JUPYTER_PASSWORD="mypassword" \
-v /usr/lib/wsl/lib:/usr/lib/wsl/lib:ro \
-v "$PWD":/workspace/host \
-v "$HOME/.cache/huggingface":/workspace/.cache/huggingface \
-v unsloth-studio:/opt/unsloth-studio \
unsloth/unsloth-rocm
```
* Exécutez-le depuis l’intérieur de WSL2 (`wsl -d Ubuntu`), depuis le dossier de votre projet, car ce dossier (`$PWD`) devient `/workspace/host`.
* Ce que font les indicateurs : `--device /dev/dxg` et le `/usr/lib/wsl/lib` et le montage transmettent le GPU via WSL2 ; les ports 8000 (Unsloth Studio) et 8888 (JupyterLab) ; les trois `-v` indicateurs conservent vos fichiers, modèles et données Unsloth Studio.
* Exigence : le pilote Windows AMD avec prise en charge de WSL2 sur l’hôte
{% endtab %}
{% tab title="Windows (PowerShell)" %}
Exécutez ce qui suit dans PowerShell :
```powershell
docker run -d --name unsloth --device /dev/dxg --ipc=host `
--ulimit memlock=-1 --ulimit stack=67108864 `
-e HSA_ENABLE_DXG_DETECTION=1 `
-e LD_LIBRARY_PATH=/usr/lib/wsl/lib:/opt/rocm/lib `
-p 8000:8000 -p 8888:8888 `
-e JUPYTER_PASSWORD="mypassword" `
-v "/usr/lib/wsl/lib:/usr/lib/wsl/lib:ro" `
-v "${PWD}:/workspace/host" `
-v "${HOME}/.cache/huggingface:/workspace/.cache/huggingface" `
-v "unsloth-studio:/opt/unsloth-studio" `
unsloth/unsloth-rocm
```
* Exécutez-le depuis le dossier de votre projet, car ce dossier (`${PWD}`) devient `/workspace/host`.
* Exigence : un pilote Windows AMD avec prise en charge de WSL2, et Docker Desktop utilisant le moteur WSL 2.
{% endtab %}
{% endtabs %}
Si Docker n’est pas installé, exécutez la commande suivante :
```bash
curl -fsSL https://get.docker.com -o get-docker.sh && sh get-docker.sh
```
AMD n’a pas besoin de kit d’outils de conteneur, seulement du `amdgpu` pilote sur l’hôte. Sous Windows, installez Docker Desktop et le pilote AMD avec prise en charge de WSL2.
### 📖 Guides d’utilisation
#### Configuration d’Unsloth Studio
Unsloth Studio est préinstallé, vous pouvez donc discuter avec des modèles, les affiner et générer des images depuis le même conteneur Docker.
{% stepper %}
{% step %}
**Démarrez le conteneur Unsloth.** \
Exécutez la commande complète `docker run` pour votre OS dans **Démarrage rapide** et attendez environ une minute pour le démarrage. Ignorez cette étape si votre conteneur est déjà en cours d’exécution.
```bash
docker start unsloth
```
{% endstep %}
{% step %}
**Trouvez vos mots de passe.** \
Si vous ne connaissez pas encore votre mot de passe, vérifiez les journaux du conteneur :
```bash
docker logs -f unsloth
```
Recherchez **Conteneur Unsloth prêt** pour les liens et les détails du mot de passe. Appuyez sur **Ctrl+C** pour arrêter de suivre les journaux ; le conteneur continue de s’exécuter.
{% endstep %}
{% step %}
**Se connecter**
Ouvrez [`http://localhost:8000`](http://localhost:8000) et connectez-vous en tant que `unsloth`. Lors de la première configuration, utilisez le mot de passe généré et choisissez-en un nouveau lorsqu’on vous le demande. Sinon, utilisez votre mot de passe existant.
{% endstep %}
{% step %}
**Mot de passe oublié ?**
```bash
docker exec unsloth unsloth studio reset-password --username unsloth
```
Cela génère un nouveau mot de passe, déconnecte les sessions existantes et révoque les clés API. Aucun redémarrage n’est nécessaire. Ces commandes supposent que votre conteneur s’appelle `unsloth`. Si nécessaire, exécutez `docker ps` pour trouver son nom ou son ID.
{% hint style="info" %}
Si Docker s’exécute sur une autre machine (comme un GPU cloud ou un serveur), `localhost` désigne votre propre ordinateur. Vous devez transférer les ports avant d’ouvrir les liens. Exécutez `ssh -L 8000:localhost:8000 -L 8888:localhost:8888 user@your-server`. Voir la [Notes de sécurité](#security-notes) section pour plus de détails.
{% endhint %}
{% endstep %}
{% endstepper %}
#### **Discuter avec un modèle**
{% hint style="info" %}
Unsloth Studio et JupyterLab partagent le même GPU. Un modèle chargé dans Unsloth conserve sa mémoire GPU jusqu’à ce que vous le déchargiez. Si vous manquez de mémoire, déchargez le modèle dans Unsloth ou arrêtez le noyau du notebook.
{% endhint %}
{% stepper %}
{% step %}
**Choisissez et téléchargez un modèle**
Ouvrez **Sélectionnez un modèle** en haut de la page. Parcourez **Recommandé**, ou entrez le nom d’un modèle et cliquez sur **Rechercher sur Hub** pour rechercher sur Hugging Face. Vous pouvez également parcourir les modèles dans **Hub de modèles**.
Pour les modèles GGUF, choisissez une quantification adaptée à votre RAM et VRAM disponibles. Évitez les variantes marquées **OOM**.
Attendez que le modèle ait fini de se télécharger et de se charger avant d’envoyer votre premier message. Vous pouvez sélectionner à nouveau les modèles téléchargés depuis **Sur l’appareil**.
Parcourez les modèles recommandés ou recherchez par nom.
{% hint style="info" %}
Les modèles téléchargés sont stockés dans `/workspace/.cache/huggingface`. Avec le montage de volume de Démarrage rapide, ce cache est partagé avec les notebooks et reste sur votre ordinateur même si vous supprimez le conteneur.
{% endhint %}
{% endstep %}
{% step %}
**Envoyer un message**
Une fois le modèle prêt, tapez un message et appuyez sur **Entrée**. Essayez :
> Expliquez en quoi les conteneurs Docker diffèrent des machines virtuelles.
Voir le [guide de chat d’Unsloth Studio](/docs/fr/nouveau/studio/chat.md) pour la recherche web et d’autres paramètres de chat.
{% endstep %}
{% endstepper %}
#### **Entraîner un modèle**
Vous pouvez entraîner des modèles sur le texte, [la vision](https://unsloth.ai/docs/basics/vision-fine-tuning) et [l’audio](https://unsloth.ai/docs/basics/text-to-speech-tts-fine-tuning), avec la prise en charge de [les embeddings](https://unsloth.ai/docs/basics/embedding-finetuning) et de la diffusion d’images également. Le tout depuis la même image Docker.
**Choisissez un modèle et un jeu de données**
Sélectionnez **Entraîner** et ouvrez **Configurer**. Choisissez un modèle et une méthode d’entraînement, puis sélectionnez un jeu de données Hugging Face ou importez le vôtre.
**Démarrer l’entraînement**
Examiner **Paramètres** dans **Simple** ou **Avancé** mode, puis cliquez sur **Lancer l’entraînement**. Suivez la progression, la perte et l’utilisation du GPU dans **Exécution en cours**.
**Essayez votre modèle entraîné**
Lorsque l’entraînement est terminé, cliquez sur **Comparer dans le chat**Testez les modèles original et affiné avec les mêmes invites pour voir en quoi leurs réponses diffèrent.
Voir le [Guide d’entraînement Studio](https://unsloth.ai/docs/new/studio/start) pour plus de détails, ou utilisez [Recettes de données](https://unsloth.ai/docs/new/studio/data-recipe) pour préparer votre jeu de données.
#### **Générer des images**
{% stepper %}
{% step %}
**Ouvrez Images et choisissez un modèle**
Sélectionnez **Images** dans la barre latérale. Le flux de travail **Créer** s’ouvre par défaut.
Ouvrez Images pour créer une image à partir d’une invite textuelle.
Ouvrez **Sélectionnez un modèle d’image** et choisissez parmi **Recommandé**, comme Z-Image-Turbo. Pour les modèles GGUF, choisissez une quantification adaptée à votre appareil. **TIGHT** peut fonctionner lentement ; **OOM** a peu de chances de tenir.
Choisissez un modèle d’image et une quantification pour votre appareil.
{% endstep %}
{% step %}
**Saisissez une invite et générez**
Décrivez l’image que vous souhaitez créer. Par exemple :
> Vue plongeante d’un bassin à carpes koï dans un jardin japonais, des dizaines de carpes koï orange, blanches et noires nageant en formation serrée, eau suffisamment claire pour voir le fond en pierre, feuilles d’érable rouges flottant à la surface. Lumière vive de midi, couleurs saturées, reflets nets. Photo réaliste, 50 mm.
Laissez les paramètres de l’image par défaut et cliquez sur **Générer**.
Un exemple de génération avec Z-Image-Turbo.
Ouvrez votre image dans la galerie et cliquez sur **Télécharger** pour l’enregistrer, ou **Recette** pour réutiliser son invite et ses paramètres.
**Transformer**, **Incruster** et **Éditer** dépendent du modèle chargé. Voir le [guide de diffusion d’images](https://unsloth.ai/docs/basics/diffusion-image) pour les flux de travail et paramètres pris en charge.
{% endstep %}
{% endstepper %}
#### **Accéder à JupyterLab**
{% columns %}
{% column %}
L’image Docker d’Unsloth inclut JupyterLab et des notebooks prêts à l’emploi.
Ouvrez [`http://localhost:8888`](http://localhost:8888) et connectez-vous. Utilisez le `JUPYTER_PASSWORD` que vous avez choisi au démarrage du conteneur. Si vous n’en avez pas défini, utilisez le mot de passe généré affiché dans le journal du conteneur.
{% hint style="info" %}
Les mots de passe de JupyterLab sont définis lors de la création du conteneur. Pour le modifier, supprimez et recréez le conteneur avec un nouveau mot de passe.
{% endhint %}
{% endcolumn %}
{% column %}
{% endcolumn %}
{% endcolumns %}
Après vous être connecté, vous verrez **Notebooks Unsloth**, avec des dossiers regroupés par modèle et tâche.
Ces dossiers contiennent des raccourcis vers les fichiers notebook dans `/workspace/unsloth-notebooks`. Chaque fois que le conteneur démarre, les notebooks sont actualisés depuis GitHub sans écraser
\
vos modifications.
Double-cliquez **01 Notebooks principaux** pour parcourir des exemples, ou choisissez une catégorie comme vision, parole ou apprentissage par renforcement.
#### **Affiner un modèle dans un notebook**
Déchargez tout modèle chargé dans Unsloth Studio avant de commencer l’entraînement, afin que le notebook dispose de la mémoire GPU dont il a besoin.
Ouvrez un notebook dans **01 Notebooks principaux** et suivez ses instructions. Appuyez sur **Shift+Enter** pour exécuter chaque cellule dans l’ordre. La première exécution télécharge le modèle dans le cache Hugging Face.
Par exemple, `Gemma3_(4B)-Vision.ipynb` vous guide pour affiner Gemma 3 4B afin de transformer des images d’équations en LaTeX.
Après l’entraînement, testez votre modèle à l’aide de la section **Inférence** du notebook. Elle teste le modèle entraîné sur une image d’équation. L’équation est ci-dessous, recréée ici en plus haute résolution pour plus de lisibilité.
Le modèle génère du LaTeX à partir de l’image d’origine du jeu de données. Il affiche le résultat LaTeX sous la cellule.
#### **Enregistrer et exporter votre modèle**
Suivez la section Saving du notebook pour enregistrer vos adaptateurs LoRA entraînés ou exporter votre modèle fusionné.
Un chemin relatif comme `"gemma_3_lora"` s’enregistre à côté du notebook, dans `/workspace/Unsloth Notebooks/...`. Ce dossier se trouve à l’intérieur du conteneur, il est donc supprimé lorsque vous supprimez le conteneur. Pour conserver vos résultats sur votre ordinateur, enregistrez dans `/workspace/host`.
* **Enregistrer les adaptateurs LoRA localement :** Cette cellule s’exécute par défaut. Modifiez le chemin en `/workspace/host`.
```python
model.save_pretrained("/workspace/host/gemma_3_lora")
processor.save_pretrained("/workspace/host/gemma_3_lora")
```
* **Exporter le modèle fusionné 16 bits :** Dans la cellule d’export, remplacez `if False:` par `if True:` pour l’option souhaitée. N’en choisissez qu’une seule.
```python
if True: model.save_pretrained_merged("/workspace/host/unsloth_finetune", processor)
```
* **Téléverser sur Hugging Face :** Vous avez besoin d’un jeton avec accès en écriture pour téléverser. Remplacez les `YOUR_USERNAME` et `YOUR_HF_TOKEN` espaces réservés par vos propres informations.
Pour plus de conseils, consultez notre [Guide de fine-tuning](https://unsloth.ai/docs/get-started/fine-tuning-llms-guide), [Guide RL](https://unsloth.ai/docs/get-started/reinforcement-learning-rl-guide), et [collection de notebooks](https://github.com/unslothai/notebooks).
#### Arrêter, redémarrer et mettre à jour le conteneur
Les commandes prennent le nom ou l’identifiant du conteneur, pas le nom de l’image `unsloth/unsloth`.
Arrêtez le conteneur mais conservez-le :
```bash
docker stop unsloth
```
Le remettre dans le même état :
```bash
docker start unsloth
```
Retrouvez à nouveau votre conteneur, qu’il soit en cours d’exécution ou non :
```bash
docker ps -a
```
Arrêtez et supprimez le conteneur :
```bash
docker rm -f unsloth
```
La suppression du conteneur ne supprime pas vos modèles, vos fichiers hôte (`/workspace/host`), ni les données d’Unsloth Studio (comptes, conversations et exportations). Un nouveau conteneur avec les mêmes `-v` options de lancement reprend là où vous vous étiez arrêté, et votre mot de passe Unsloth reste le même. Tout ce qui est écrit à l’intérieur du conteneur est perdu.
Pour supprimer définitivement les données d’Unsloth Studio, supprimez son volume :
```bash
docker volume rm unsloth-studio
```
Pour mettre à jour vers la dernière version d’Unsloth, récupérez la nouvelle image :
```bash
#GPU NVIDIA
docker pull unsloth/unsloth
#GPU AMD
docker pull unsloth/unsloth-rocm
```
Supprimez ensuite l’ancien conteneur et relancez la commande Quickstart avec les mêmes options. Vos modèles, fichiers et données Unsloth Studio sont conservés.
```bash
docker rm -f unsloth
```
#### **Connexion via SSH**
SSH est désactivé sauf si vous définissez `SSH_KEY` ou `PUBLIC_KEY`. Vous vous connectez en tant qu’ `root` utilisateur avec authentification par clé uniquement sur le port 22 à l’intérieur du conteneur.
Générez une clé SSH :
```bash
ssh-keygen -t ed25519 -f ~/.ssh/container_key
```
La clé SSH est appliquée lors de la création du conteneur, donc vous devez recréer le conteneur pour l’ajouter. Utilisez cette commande complète pour mapper le port SSH sur 2222 sur votre hôte, définir vos mots de passe et monter vos volumes.
{% tabs %}
{% tab title="NVIDIA" %}
```bash
docker run -d --name unsloth --gpus all --ipc=host \
--ulimit memlock=-1 --ulimit stack=67108864 \
-p 8000:8000 -p 8888:8888 -p 2222:22 \
-e JUPYTER_PASSWORD="choisissez-un-mot-de-passe-jupyter" \
-e UNSLOTH_STUDIO_PASSWORD="choisissez-un-mot-de-passe-studio" \
-e SSH_KEY="$(cat ~/.ssh/container_key.pub)" \
-v "$PWD":/workspace/host \
-v "$HOME/.cache/huggingface":/workspace/.cache/huggingface \
-v unsloth-studio:/opt/unsloth-studio \
unsloth/unsloth
```
{% endtab %}
{% tab title="AMD" %}
```bash
GPU_FLAGS="--device /dev/kfd"
[ -e /dev/dri ] && GPU_FLAGS="$GPU_FLAGS --device /dev/dri"
for g in video render; do
gid=$(getent group "$g" | cut -d: -f3)
[ -n "$gid" ] && GPU_FLAGS="$GPU_FLAGS --group-add $gid"
done
docker run -d --name unsloth $GPU_FLAGS --ipc=host \
--ulimit memlock=-1 --ulimit stack=67108864 \
-p 8000:8000 -p 8888:8888 -p 2222:22 \
-e JUPYTER_PASSWORD="choisissez-un-mot-de-passe-jupyter" \
-e UNSLOTH_STUDIO_PASSWORD="choisissez-un-mot-de-passe-studio" \
-e SSH_KEY="$(cat ~/.ssh/container_key.pub)" \
-v "$PWD":/workspace/host \
-v "$HOME/.cache/huggingface":/workspace/.cache/huggingface \
-v unsloth-studio:/opt/unsloth-studio \
unsloth/unsloth-rocm
```
{% endtab %}
{% endtabs %}
`UNSLOTH_STUDIO_PASSWORD` s’applique uniquement la première fois que le volume `unsloth-studio` est utilisé. Voir [Paramètres avancés](#advanced-settings) ci-dessous pour toutes les variables d’environnement, volumes et ports.
Connectez-vous au conteneur :
```bash
ssh -i ~/.ssh/container_key -p 2222 root@localhost
```
#### 📂 Structure du conteneur
* `/workspace/host/` — Votre répertoire de travail monté
* `/workspace/.cache/huggingface` — Téléchargements de modèles et de jeux de données
* `/workspace/.cache/triton` — Noyaux Triton compilés
* `/workspace/unsloth-notebooks/` — Notebooks d’exemple pour le fine-tuning, y compris vos modifications
* `/workspace/Unsloth Notebooks` — Notebooks d’exemple pour le fine-tuning regroupés par thème, reconstruits à chaque démarrage
* `/opt/unsloth-studio` — Comptes, conversations, sorties, exportations et exécutions d’Unsloth Studio
### Dépannage
#### **Unsloth ne détecte pas ou n’utilise pas mon GPU**
Si le modèle n’utilise pas spécifiquement votre GPU pour Docker, essayez :
Récupérer manuellement la dernière image :
```bash
#GPU NVIDIA
docker pull unsloth/unsloth:latest
#GPU AMD
docker pull unsloth/unsloth-rocm:latest
```
* Démarrez le conteneur avec l’accès au GPU :
* `docker run`: `--gpus all`
* Docker Compose : `capabilities: [gpu]`
* AMD : `--device /dev/kfd --device /dev/dri` plus les `--group-add` identifiants (le `$GPU_FLAGS` bloc dans Quickstart)
* Sur Linux (NVIDIA), assurez-vous que le NVIDIA Container Toolkit est installé et que docker a été redémarré après son installation.
* Sur Windows (NVIDIA) :
* Exécutez `docker exec unsloth nvidia-smi`. S’il affiche votre GPU, le conteneur peut le voir.
* Suivez [le guide de Docker](< https://docs.docker.com/desktop/features/gpu/>)
* Sur AMD : exécutez `docker exec unsloth rocm-smi`. S’il affiche votre GPU, le conteneur peut le voir. Une erreur d’autorisation sur `/dev/kfd` signifie que les `--group-add` identifiants manquaient.
#### Le port est déjà attribué
Changez le port côté hôte, par exemple `-p 8001:8000`, puis ouvrez [http://localhost:8001](http://localhost:8001/).
#### Unsloth Studio a cessé de répondre après une heure
Unsloth Studio s’arrête automatiquement si le mot de passe généré automatiquement n’est pas modifié. Exécutez `docker restart unsloth` pour le relancer et changer le mot de passe.
#### Les fichiers de votre dossier projet appartiennent à root
Le conteneur s’exécute en tant que root, donc utilisez `sudo chown`, ou `core` avec `--user`.
### ⚙️ Paramètres avancés
#### Variables d’environnement
Passez n’importe lequel de ceux-ci à `docker run` avec `-e NAME=value` ou `--env-file`. Ceux-ci s’appliquent à la fois à `unsloth/unsloth` et `unsloth/unsloth-rocm`.
| Variable | Description | Par défaut |
| ---------------------------------- | -------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
| `UNSLOTH_STUDIO_PASSWORD` | Mot de passe initial d’Unsloth Studio pour l’utilisateur `unsloth` | Non défini : généré une fois et affiché dans `docker logs` |
| `JUPYTER_PASSWORD` | Mot de passe JupyterLab | Non défini : généré une fois et affiché dans `docker logs` |
| `JUPYTER_PORT` | Port JupyterLab à l’intérieur du conteneur | `8888` |
| `UNSLOTH_STUDIO_PORT` | Port d’Unsloth Studio à l’intérieur du conteneur | `8000` |
| `UNSLOTH_STUDIO_BOOTSTRAP_TIMEOUT` | Nombre de secondes avant qu’Unsloth Studio ne s’arrête si le mot de passe généré n’est pas modifié | `3600` |
| `SSH_KEY` ou `PUBLIC_KEY` | Clé publique SSH pour `root` connexion | Non défini : SSH désactivé |
| `UNSLOTH_ALLOW_CPU` | Autoriser le conteneur à démarrer sans GPU | `1`, non défini lorsqu’un GPU est visible |
| `UNSLOTH_STUDIO_SECURE` | Servir Unsloth Studio uniquement via un lien HTTPS Cloudflare public | `0` |
| `UNSLOTH_STUDIO_CLOUDFLARE` | Partager Unsloth Studio via un lien Cloudflare public | `0` |
| `UNSLOTH_JUPYTER_CLOUDFLARE` | Partager JupyterLab via un lien Cloudflare public | `0` |
| `UNSLOTH_SKIP_NOTEBOOK_REFRESH` | Ignorer la mise à jour des notebooks d’exemple depuis GitHub | `0` |
| `UNSLOTH_SKIP_NOTEBOOK_SYNC` | Ignorer la configuration des notebooks d’exemple | `0` |
| `HF_TOKEN` | Jeton d’accès Hugging Face | Non défini |
| `WANDB_API_KEY` | Clé API Weights & Biases | Non défini |
#### Volume
{% hint style="warning" %}
**Important**: Utilisez des montages de volume pour conserver votre travail entre les exécutions du conteneur.
{% endhint %}
Tout ce qui n’est pas sur un volume est perdu lorsque le conteneur est supprimé. Montez-les avec `-v :`.
| Chemin du conteneur | Description | Montage suggéré |
| ------------------------------- | -------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| `/workspace/host` | Les fichiers de votre projet | Votre dossier projet, par exemple `"$PWD"` |
| `/workspace/.cache/huggingface` | Modèles et jeux de données téléchargés | Votre cache Hugging Face sur l’hôte, par exemple `"$HOME/.cache/huggingface"` |
| `/opt/unsloth-studio` | Comptes, conversations, modèles entraînés, exportations et exécutions d’Unsloth Studio | Volume nommé `unsloth-studio` |
| `/workspace/unsloth-notebooks` | Notebooks d’exemple, y compris vos modifications | Facultatif |
| `/workspace/.cache/triton` | Noyaux GPU compilés | Facultatif, accélère les redémarrages |
* `/workspace` est le répertoire de travail et le dossier dans lequel JupyterLab s’ouvre.
* Utilisez un volume nommé pour `/opt/unsloth-studio`, pas un dossier hôte. Unsloth Studio a besoin de liens symboliques à cet endroit, et un dossier hôte Windows ou macOS peut ne pas les autoriser, ce qui empêche le conteneur de démarrer.
* Pour donner à Unsloth Studio ou à JupyterLab davantage de vos fichiers, montez d’autres dossiers sous `/workspace`, par exemple `-v /data/datasets:/workspace/datasets`, et référez-vous-y en utilisant ce chemin de conteneur.
#### Ports
| Port | Service |
| ------ | ------------------------------------------- |
| `8000` | Unsloth Studio |
| `8888` | JupyterLab |
| `22` | SSH (uniquement quand `SSH_KEY` est défini) |
Mappez un port de conteneur vers n’importe quel port hôte libre avec `-p :`. Par exemple, pour activer SSH sur le port hôte `2222`:
{% tabs %}
{% tab title="NVIDIA" %}
```bash
docker run -d --name unsloth --gpus all \
-p 8000:8000 -p 8888:8888 -p 2222:22 \
-e SSH_KEY="$(cat ~/.ssh/id_ed25519.pub)" \
-v "$PWD":/workspace/host \
-v "$HOME/.cache/huggingface":/workspace/.cache/huggingface \
-v unsloth-studio:/opt/unsloth-studio \
unsloth/unsloth
```
{% endtab %}
{% tab title="AMD" %}
```bash
GPU_FLAGS="--device /dev/kfd"
[ -e /dev/dri ] && GPU_FLAGS="$GPU_FLAGS --device /dev/dri"
for g in video render; do
gid=$(getent group "$g" | cut -d: -f3)
[ -n "$gid" ] && GPU_FLAGS="$GPU_FLAGS --group-add $gid"
done
docker run -d --name unsloth $GPU_FLAGS \
-p 8000:8000 -p 8888:8888 -p 2222:22 \
-e SSH_KEY="$(cat ~/.ssh/id_ed25519.pub)" \
-v "$PWD":/workspace/host \
-v "$HOME/.cache/huggingface":/workspace/.cache/huggingface \
-v unsloth-studio:/opt/unsloth-studio \
unsloth/unsloth-rocm
```
{% endtab %}
{% endtabs %}
### **🔒 Notes de sécurité**
* Le conteneur s’exécute en tant que root. Utilisez `unsloth/unsloth:core` avec `--user :` si vous avez besoin que les fichiers montés appartiennent à votre utilisateur hôte.
* SSH est désactivé sauf si `SSH_KEY` ou `PUBLIC_KEY` est défini. Il est limité à l’authentification par clé, en tant que root, sur le port 22.
* Les ports publiés écoutent sur toutes les interfaces. Sur un hôte cloud, liez-les à `127.0.0.1` ou utilisez `-e UNSLOTH_STUDIO_SECURE=1`.
* JupyterLab est un shell complet. Toute personne pouvant se connecter à JupyterLab peut exécuter n’importe quelle commande dans le conteneur. Unsloth Studio et JupyterLab servent du HTTP non chiffré, donc ne les exposez pas directement à Internet.
* Les outils d’Unsloth Studio peuvent exécuter du code. Les outils côté serveur de Studio sont activés par défaut et peuvent exécuter des commandes à l’intérieur du conteneur. Ne montez que les dossiers hôte pour lesquels vous êtes à l’aise de donner l’accès au conteneur.
* Les variables d’environnement sont visibles pour les utilisateurs de Docker. Les valeurs passées avec `-e` ou `--env-file`, y compris les jetons et les mots de passe, apparaissent dans `docker inspect`. Toute personne ayant accès au démon Docker peut les lire.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://unsloth.ai/docs/fr/commencer/install/docker.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
.png?alt=media&token=ff61651a-4560-4473-9232-d06024cb216e)
.png?alt=media&token=6f1b3e41-2c5a-4c5a-9c75-f624c6f4ede6)
.png?alt=media&token=47888a19-5384-4ace-b5d7-f90cf4fb9b0f)
