# Installation d'Unsloth Studio

Unsloth Studio fonctionne sous Windows, Linux, WSL et MacOS. Vous devez utiliser le même processus d’installation sur chaque appareil, bien que les exigences système puissent varier selon l’appareil.

<a href="#windows" class="button secondary" data-icon="windows">Windows</a><a href="#macos" class="button secondary" data-icon="apple">MacOS</a><a href="#linux-and-wsl" class="button secondary" data-icon="linux">Linux & WSL</a><a href="#docker" class="button secondary" data-icon="docker">Docker</a><a href="#developer-installation-advanced" class="button secondary" data-icon="screwdriver-wrench">Installation développeur</a>

* **Mac :** Comme CPU - [Chat](https://unsloth.ai/docs/fr/nouveau/chat#using-unsloth-studio-chat) + [Recettes de données](https://unsloth.ai/docs/fr/nouveau/studio/data-recipe) fonctionne pour l’instant. **MLX** l’entraînement arrive très bientôt.
* **CPU : Unsloth fonctionne toujours sans GPU**, mais pour le Chat + les Recettes de données.
* **Entraînement :** Fonctionne sur **NVIDIA**: RTX 30, 40, 50, Blackwell, DGX Spark/Station, etc. + **Intel** GPU
* **Bientôt disponible :** Prise en charge de **Apple MLX** et **AMD**.

## Instructions d’installation

N’oubliez pas que les instructions d’installation sont les mêmes sur tous les appareils :

{% stepper %}
{% step %}

#### Installer Unsloth

**MacOS, Linux, WSL :**

```bash
curl -fsSL https://unsloth.ai/install.sh | sh
```

**Windows PowerShell :**

```bash
irm https://unsloth.ai/install.ps1 | iex
```

{% hint style="success" %}
**La première installation devrait maintenant être 6 fois plus rapide et 50 % plus légère grâce aux binaires llama.cpp précompilés.**
{% endhint %}

{% hint style="info" %}
**Utilisateurs WSL :** vous serez invité à saisir votre `sudo` mot de passe pour installer les dépendances de compilation (`cmake`, `git`, `libcurl4-openssl-dev`).
{% endhint %}
{% endstep %}

{% step %}

#### Lancer Unsloth Studio

```bash
unsloth studio -H 0.0.0.0 -p 8888
```

<div data-with-frame="true"><figure><img src="https://550366147-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2Fd1yMMNa65Ccz50Ke0E7r%2FScreenshot%202026-03-17%20at%2012.32.38%E2%80%AFAM.png?alt=media&#x26;token=9369cfe7-35b1-4955-b8cb-42f7ecb43780" alt="" width="375"><figcaption></figcaption></figure></div>

**Puis ouvrez `http://localhost:8888` dans votre navigateur.**
{% endstep %}

{% step %}

#### Intégration

Au premier lancement, vous devrez créer un mot de passe pour sécuriser votre compte et vous reconnecter plus tard. Vous verrez ensuite un bref assistant d’intégration pour choisir un modèle, un jeu de données et des paramètres de base. Vous pouvez le passer à tout moment.
{% endstep %}

{% step %}

#### Commencer l’entraînement et l’exécution

Commencez immédiatement à affiner les modèles et à créer des jeux de données après le lancement. Consultez notre guide étape par étape pour démarrer avec Unsloth Studio :

{% content-ref url="start" %}
[start](https://unsloth.ai/docs/fr/nouveau/studio/start)
{% endcontent-ref %}
{% endstep %}
{% endstepper %}

### Mettre à jour Unsloth Studio :

Pour mettre à jour Unsloth Studio, utilisez :

{% code overflow="wrap" %}

```bash
unsloth studio update 
```

{% endcode %}

Si cela ne fonctionne pas, vous pouvez utiliser ce qui suit :

#### **MacOS, Linux, WSL :**

```bash
curl -fsSL https://unsloth.ai/install.sh | sh
```

#### **Windows PowerShell :**

```bash
irm https://unsloth.ai/install.ps1 | iex
```

## Configuration système requise

### <i class="fa-windows">:windows:</i> Window**s**

Unsloth Studio fonctionne directement sous Windows sans WSL. Pour entraîner des modèles, assurez-vous que votre système répond à ces exigences :

**Exigences**

* Windows 10 ou Windows 11 (64 bits)
* GPU NVIDIA avec pilotes installés
* **App Installer** (inclut `winget`): [ici](https://learn.microsoft.com/en-us/windows/msix/app-installer/install-update-app-installer)
* **Git**: `winget install --id Git.Git -e --source winget`
* **Python**: version 3.11 jusqu’à, mais sans inclure, 3.14
* Travaillez dans un environnement Python tel que **uv**, **venv**, ou **conda/mamba**

### <i class="fa-apple">:apple:</i> MacOS

Unsloth Studio fonctionne sur les appareils Mac pour [Chat](#run-models-locally) pour les modèles GGUF et [Recettes de données](https://unsloth.ai/docs/fr/nouveau/studio/data-recipe) ([Exportation](https://unsloth.ai/docs/fr/nouveau/studio/export) bientôt disponible). **L’entraînement MLX arrive bientôt !**

* macOS 12 Monterey ou plus récent (Intel ou Apple Silicon)
* Installez Homebrew : [ici](https://brew.sh/)
* Git : `brew install git`&#x20;
* cmake : `brew install cmake`&#x20;
* openssl : `brew install openssl`
* Python : version 3.11 jusqu’à, mais sans inclure, 3.14
* Travaillez dans un environnement Python tel que **uv**, **venv**, ou **conda/mamba**

### <i class="fa-linux">:linux:</i> Linux & WSL

* Ubuntu 20.04+ ou distribution similaire (64 bits)
* GPU NVIDIA avec pilotes installés
* CUDA toolkit (12.4+ recommandé, 12.8+ pour Blackwell)
* Git : `sudo apt install git`
* Python : version 3.11 jusqu’à, mais sans inclure, 3.14
* Travaillez dans un environnement Python tel que **uv**, **venv**, ou **conda/mamba**

### <i class="fa-docker">:docker:</i> Docker

{% hint style="success" %}
Notre image Docker fonctionne maintenant pour Studio ! Nous travaillons sur la compatibilité Mac.
{% endhint %}

* Téléchargez notre dernière image conteneur Unsloth : `docker pull unsloth/unsloth`
* Lancez le conteneur via :

```bash
docker run -d -e JUPYTER_PASSWORD="mypassword" \
  -p 8888:8888 -p 8000:8000 -p 2222:22 \
  -v $(pwd)/work:/workspace/work \
  --gpus all \
  unsloth/unsloth
```

Pour plus d’informations, [voir ici](https://hub.docker.com/r/unsloth/unsloth#unsloth-docker-image).

* Accédez à votre instance Studio à `http://localhost:8000` ou à l’adresse IP externe `http://external_ip_address:8000/`

### <i class="fa-microchip">:microchip:</i> CPU uniquement

Unsloth Studio prend en charge les appareils CPU pour [Chat](#run-models-locally) pour les modèles GGUF et [Recettes de données](https://unsloth.ai/docs/fr/nouveau/studio/data-recipe) ([Exportation](https://unsloth.ai/docs/fr/nouveau/studio/export) bientôt disponible)

* Identique à celles mentionnées ci-dessus pour Linux (sauf pour les pilotes GPU NVIDIA) et MacOS.

## Installation développeur (avancée)

### **Installer depuis le dépôt principal**

#### **Installations développeur macOS, Linux, WSL :**

```bash
git clone https://github.com/unslothai/unsloth
cd unsloth
./install.sh --local
unsloth studio -H 0.0.0.0 -p 8888
```

#### **Installations développeur Windows PowerShell :**

```powershell
winget install -e --id Python.Python.3.13 --source winget
winget install --id=astral-sh.uv  -e --source winget
winget install --id Git.Git -e --source winget
git clone https://github.com/unslothai/unsloth
cd unsloth
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
.\install.ps1 --local
unsloth studio -H 0.0.0.0 -p 8888
```

### **Installation nocturne**

#### **Nocturne - MacOS, Linux, WSL :**

```bash
git clone https://github.com/unslothai/unsloth
cd unsloth
git checkout nightly
./install.sh --local
```

Puis pour lancer à chaque fois :

```bash
unsloth studio -H 0.0.0.0 -p 8888
```

#### **Nocturne - Windows :**

Exécutez dans Windows PowerShell :

```bash
winget install -e --id Python.Python.3.13 --source winget
winget install --id=astral-sh.uv  -e --source winget
winget install --id Git.Git -e --source winget
git clone https://github.com/unslothai/unsloth
cd unsloth
git checkout nightly
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
.\install.ps1 --local
```

Puis pour lancer à chaque fois :

<pre class="language-bash"><code class="lang-bash"><strong>unsloth studio -H 0.0.0.0 -p 8888
</strong></code></pre>

### Désinstaller

Pour désinstaller Unsloth Studio, suivez ces 4 étapes :

#### **1. Supprimer l’application**

* MacOS, WSL, Linux : `rm -rf ~/.unsloth/studio/unsloth ~/.unsloth/studio/studio`
* Windows (PowerShell) : `Remove-Item -Recurse -Force "$HOME\.unsloth\studio\unsloth", "$HOME\.unsloth\studio\studio"`&#x20;

Cela supprime l’application mais conserve vos checkpoints de modèle, exports, historique, cache et chats.

#### **2. Supprimer les raccourcis et les liens symboliques**

**macOS :**

```bash
rm -rf ~/Applications/Unsloth\ Studio.app ~/Desktop/Unsloth\ Studio
```

**Linux :**

```bash
rm -f ~/.local/share/applications/unsloth-studio.desktop ~/Desktop/unsloth-studio.desktop
```

**WSL / Windows (PowerShell) :**

```bash
Remove-Item -Force "$HOME\Desktop\Unsloth Studio.lnk"
Remove-Item -Force "$env:APPDATA\Microsoft\Windows\Start Menu\Programs\Unsloth Studio.lnk"
```

#### **3. Supprimer la commande CLI**

**macOS, Linux, WSL :**

```bash
rm -f ~/.local/bin/unsloth
```

**Windows (PowerShell) :** L’installateur a ajouté le répertoire `Scripts` du venv à votre PATH utilisateur. Pour le supprimer, ouvrez Paramètres → Système → À propos → Paramètres système avancés → Variables d’environnement, recherchez `Path` dans Variables utilisateur, et supprimez l’entrée pointant vers `.unsloth\studio\...\Scripts`.

#### **4. Tout supprimer (facultatif)**

Pour supprimer aussi l’historique, le cache, les chats, les checkpoints de modèle et les exports de modèle, supprimez tout le dossier Unsloth :

* MacOS, WSL, Linux : `rm -rf ~/.unsloth`
* Windows (PowerShell) : `Remove-Item -Recurse -Force "$HOME\.unsloth"`&#x20;

Notez que les fichiers de modèle HF téléchargés sont stockés séparément dans le cache Hugging Face — aucune des étapes ci-dessus ne les supprimera. Voir **Suppression des fichiers de modèle** ci-dessous si vous souhaitez récupérer cet espace disque.

{% hint style="warning" %}
Remarque : l’utilisation des `rm -rf` commandes va **tout supprimer**, y compris votre historique, cache, chats, etc.
{% endhint %}

### **Suppression des fichiers de modèle HF en cache**

Vous pouvez supprimer les anciens fichiers de modèle soit depuis l’icône de corbeille dans la recherche de modèles, soit en supprimant le dossier de modèle mis en cache correspondant du répertoire de cache Hugging Face par défaut. Par défaut, Hugging Face utilise `~/.cache/huggingface/hub/` sur macOS/Linux/WSL et `C:\Users\<username>\.cache\huggingface\hub\` sur Windows.

* **MacOS, Linux, WSL :** `~/.cache/huggingface/hub/`
* **Windows :** `%USERPROFILE%\.cache\huggingface\hub\`

Si `HF_HUB_CACHE` ou `HF_HOME` est défini, utilisez plutôt cet emplacement. Sous Linux et WSL, `XDG_CACHE_HOME` peut également modifier la racine de cache par défaut.

### Utilisation d’anciens modèles GGUF / déjà existants

{% columns %}
{% column %}
**Mise à jour du 1er avril :** Vous pouvez maintenant sélectionner un dossier existant à partir duquel Unsloth doit détecter.

**Mise à jour du 27 mars :** Unsloth Studio détecte désormais **automatiquement les modèles plus anciens / préexistants** téléchargés depuis Hugging Face, LM Studio, etc.
{% endcolumn %}

{% column %}

<figure><img src="https://550366147-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FBn3Fs1cchFchl328wSOs%2FScreenshot%202026-04-05%20at%205.43.57%E2%80%AFAM.png?alt=media&#x26;token=cc57ec6e-653a-4824-8e8d-a6bfbcd27493" alt=""><figcaption></figcaption></figure>
{% endcolumn %}
{% endcolumns %}

**Instructions manuelles :** Unsloth Studio détecte les modèles téléchargés dans votre cache Hugging Face Hub `(C:\Users{your_username}.cache\huggingface\hub)`. Si vous avez téléchargé des modèles GGUF via LM Studio, notez qu’ils sont stockés dans `C:\Users{your_username}.cache\lm-studio\models` ***OU*** `C:\Users{your_username}\lm-studio\models` . Parfois, lorsqu’ils ne sont pas visibles, vous devrez déplacer ou copier ces fichiers .gguf dans votre répertoire de cache Hugging Face Hub (ou dans un autre chemin accessible à llama.cpp) pour qu’Unsloth Studio puisse les charger.

Après avoir affiné un modèle ou un adaptateur dans Studio, vous pouvez l’exporter en GGUF et exécuter l’inférence locale avec **llama.cpp** directement dans le Chat Studio. Unsloth Studio est propulsé par llama.cpp et Hugging Face.

### <i class="fa-google">:google:</i> Notebook Google Colab

Nous avons créé un [notebook Google Colab gratuit](https://colab.research.google.com/github/unslothai/unsloth/blob/main/studio/Unsloth_Studio_Colab.ipynb) pour que vous puissiez explorer toutes les fonctionnalités d’Unsloth sur les GPU T4 de Colab. Vous pouvez entraîner et exécuter la plupart des modèles jusqu’à 22 milliards de paramètres, et passer à un GPU plus grand pour les modèles plus volumineux. Cliquez simplement sur « Run all » et l’interface devrait apparaître après l’installation.

{% columns %}
{% column %}
{% embed url="<https://colab.research.google.com/github/unslothai/unsloth/blob/main/studio/Unsloth_Studio_Colab.ipynb>" %}

Une fois l’installation terminée, faites défiler jusqu’à **Démarrer Unsloth Studio** et cliquez sur **Ouvrir Unsloth Studio** dans la boîte blanche affichée à gauche :

**Faites défiler plus bas pour voir l’interface réelle.**
{% endcolumn %}

{% column %}

<div data-with-frame="true"><figure><img src="https://550366147-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FkYitMrK55Ic6eIGqiKEJ%2FScreenshot%202026-03-16%20at%2011.21.16%E2%80%AFPM.png?alt=media&#x26;token=4388c309-a598-41f3-9301-e434c334ac1c" alt=""><figcaption></figcaption></figure></div>
{% endcolumn %}
{% endcolumns %}

{% hint style="warning" %}
Parfois, le lien Studio peut renvoyer une erreur. Cela se produit parce que vous avez peut-être désactivé les cookies ou que vous utilisez un bloqueur de publicités ou Mozilla. Vous pouvez toujours accéder à l’interface en faisant défiler sous le bouton.

Google Colab s’attend également à ce que vous restiez sur la page Colab ; s’il détecte une inactivité, il peut fermer la session GPU.
{% endhint %}

## Dépannage

<table><thead><tr><th width="211.5999755859375">Problème</th><th>Correction</th></tr></thead><tbody><tr><td>Erreur de version de Python</td><td><code>sudo apt install python3.12 python3.12-venv</code> version 3.11 jusqu’à, mais sans inclure, 3.14</td></tr><tr><td><code>nvidia-smi introuvable</code></td><td>Installez les pilotes NVIDIA depuis https://www.nvidia.com/Download/index.aspx</td></tr><tr><td><code>nvcc introuvable</code> (CUDA)</td><td><code>sudo apt install nvidia-cuda-toolkit</code> ou ajoutez <code>/usr/local/cuda/bin</code> au PATH</td></tr><tr><td>échec de la compilation de llama-server</td><td>Non fatal, Studio fonctionne toujours, l’inférence GGUF ne sera pas disponible. Installez <code>cmake</code> et relancez la configuration pour corriger le problème.</td></tr><tr><td><code>cmake introuvable</code></td><td><code>sudo apt install cmake</code></td></tr><tr><td><code>git introuvable</code></td><td><code>sudo apt install git</code></td></tr><tr><td>Échec de la compilation</td><td>Supprimez <code>~/.unsloth/llama.cpp</code> et relancez la configuration</td></tr></tbody></table>