# Unsloth Studio Installation Unsloth Studio works on Windows, Linux, WSL and MacOS. You should use the same installation process on every device, although the system requirements may differ by device. Windows MacOS Linux & WSL Docker Developer Install * **Mac:** Like CPU - [Chat](/docs/new/studio/chat.md#using-unsloth-studio-chat) + [Data Recipes](/docs/new/studio/data-recipe.md) works for now. **MLX** training coming very soon. * **CPU: Unsloth still works without a GPU**, but for Chat + Data Recipes. * **Training:** Works on **NVIDIA**: RTX 30, 40, 50, Blackwell, DGX Spark/Station etc. + **Intel** GPUs * **Coming soon:** Support for **Apple MLX** and **AMD**. ### Quickstart {% tabs %} {% tab title="MacOS" %} #### Step 1: Setup Unsloth Launch the `terminal` from Mac, then install Unsloth by entering the command below. ```bash curl -fsSL https://unsloth.ai/install.sh | sh ``` Unsloth will start setting up the environment and installing the required packages as shown below. Type **Y** and Press `Enter` when asked if you want to allow Studio to start now. This will start Unsloth on your local **8888** port.

{% hint style="info" %} If you chose not to start Unsloth during the installation process, you can always start the Unsloth app using `unsloth studio -p 8888` . If you would like to have your Unsloth instance accessible by clients outside of your PC/computer, add `-H 0.0.0.0` to the `unsloth studio` command. {% endhint %} #### Step 2: Start Unsloth Open your browser of choice and go to the `http://127.0.0.1:8888` URL. If this is your first time installing Unsloth, you will be prompted to create a new password. After, the Unsloth app should now open on the Chat Page as shown below.

You can also launch it with the following command: ```bash unsloth studio -H 0.0.0.0 -p 8888 ``` {% hint style="info" %} If you would like to have your instance accessible by clients outside of your PC/computer.\ Add `-H 0.0.0.0` to the `unsloth studio` command. {% endhint %} #### Step 2: Start Unsloth Open `http://127.0.0.1:8888` in your browser. On first launch, create a new password to continue to the Chat page. **Unsloth Studio** is now installed and ready to use. The Unsloth app should now open on the Chat Page as shown below.

{% hint style="info" %} If you chose not to start Unsloth during the installation process, you can always start the Unsloth app using `unsloth studio -p 8888` . If you would like to have your Unsloth instance accessible by clients outside of your PC/computer, add `-H 0.0.0.0` to the `unsloth studio` command. {% endhint %} #### Step 2: Start Unsloth Open your browser of choice and type `http://127.0.0.1:8888` in the URL box. If this is your first time installing Unsloth, you will be forwarded to `http://127.0.0.1:8888/change-password` page as shown below:

Type a new password in the `New Password` field and re-type the same password in `Confirm Password` then click the **Change password** button**.**

The Unsloth app should now open on the Chat Page as shown. **Unsloth Studio** is now installed and ready to use.

You can start training and running models immediately. You can view our more detailed step-by-step guide to get started below: {% content-ref url="/pages/vrLQd9559vRkDY8zRR0h" %} [Get Started](/docs/new/studio/start.md) {% endcontent-ref %} {% endtab %} {% endtabs %} ### Update Unsloth Studio To update Unsloth Studio use: {% code overflow="wrap" %} ```bash unsloth studio update ``` {% endcode %} If that does not work, you can use the below: #### **MacOS, Linux, WSL:** ```bash curl -fsSL https://unsloth.ai/install.sh | sh ``` #### **Windows PowerShell:** ```bash irm https://unsloth.ai/install.ps1 | iex ``` ## System Requirements ### Window**s** Unsloth Studio works directly on Windows without WSL. To train models, make sure your system satisfies these requirements: **Requirements** * Windows 10 or Windows 11 (64-bit) * NVIDIA GPU with drivers installed * **App Installer** (includes `winget`): [here](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 up to, but not including, 3.14 * Work inside a Python environment such as **uv**, **venv**, or **conda/mamba** ### MacOS Unsloth Studio works on Mac devices for [Chat](#run-models-locally) for GGUF models and [Data Recipes](/docs/new/studio/data-recipe.md) ([Export](/docs/new/studio/export.md) coming very soon). **MLX training coming soon!** * macOS 12 Monterey or newer (Intel or Apple Silicon) * Install Homebrew: [here](https://brew.sh/) * Git: `brew install git` * cmake: `brew install cmake` * openssl: `brew install openssl` * Python: version 3.11 up to, but not including, 3.14 * Work inside a Python environment such as **uv**, **venv**, or **conda/mamba** ### Linux & WSL * Ubuntu 20.04+ or similar distro (64-bit) * NVIDIA GPU with drivers installed * CUDA toolkit (12.4+ recommended, 12.8+ for blackwell) * Git: `sudo apt install git` * Python: version 3.11 up to, but not including, 3.14 * Work inside a Python environment such as **uv**, **venv**, or **conda/mamba** ### Docker {% hint style="success" %} Our Docker image now works for Studio! We're working on Mac compatibility. {% endhint %} * Pull our latest Unsloth container image: `docker pull unsloth/unsloth` * Run the container 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 ``` For more information, [see here](https://hub.docker.com/r/unsloth/unsloth#unsloth-docker-image). * Access your studio instance at `http://localhost:8000` or external ip address `http://external_ip_address:8000/` ### CPU only Unsloth Studio supports CPU devices for [Chat](#run-models-locally) for GGUF models and [Data Recipes](/docs/new/studio/data-recipe.md) ([Export](/docs/new/studio/export.md) coming very soon) * Same as the ones mentioned above for Linux (except for NVIDIA GPU drivers) and MacOS. ## Developer Installation (Advanced) ### **Main Repo Install** #### **macOS, Linux, WSL developer installs:** ```bash git clone https://github.com/unslothai/unsloth cd unsloth ./install.sh --local unsloth studio -H 0.0.0.0 -p 8888 ``` #### **Windows PowerShell developer installs:** ```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 ``` ### **Nightly Install** #### **Nightly - MacOS, Linux, WSL:** ```bash git clone https://github.com/unslothai/unsloth cd unsloth git checkout nightly ./install.sh --local ``` Then to launch every time: ```bash unsloth studio -H 0.0.0.0 -p 8888 ``` #### **Nightly - Windows:** Run in 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 ``` Then to launch every time:

unsloth studio -H 0.0.0.0 -p 8888

### Uninstall To uninstall Unsloth Studio, follow these 4 steps: #### **1. Remove the application** * MacOS, WSL, Linux: `rm -rf ~/.unsloth/studio/unsloth_studio` * Windows (PowerShell): `Remove-Item -Recurse -Force "$HOME\.unsloth\studio\unsloth_studio"` This removes the application but keeps your model checkpoints, exports, history, cache, and chats intact. #### **2. Remove shortcuts and symlinks** **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. Remove the CLI command** **macOS, Linux, WSL:** ```bash rm -f ~/.local/bin/unsloth ``` **Windows (PowerShell):** The installer added the venv's `Scripts` directory to your User PATH. To remove it, open Settings → System → About → Advanced system settings → Environment Variables, find `Path` under User variables, and remove the entry pointing to `.unsloth\studio\...\Scripts`. #### **4. Remove everything (optional)** To also delete history, cache, chats, model checkpoints, and model exports, delete the entire Unsloth folder: * MacOS, WSL, Linux: `rm -rf ~/.unsloth` * Windows (PowerShell): `Remove-Item -Recurse -Force "$HOME\.unsloth"` Note that downloaded HF model files are stored separately in the Hugging Face cache — none of the steps above will remove them. See **Deleting model files** below if you want to reclaim that disk space. {% hint style="warning" %} Note: Using the `rm -rf` commands will **delete everything**, including your history, cache, chats etc. {% endhint %} ### **Deleting cached HF model files** You can delete old model files either from the bin icon in model search or by removing the relevant cached model folder from the default Hugging Face cache directory. By default, Hugging Face uses `~/.cache/huggingface/hub/` on macOS/Linux/WSL and `C:\Users\\.cache\huggingface\hub\` on Windows. * **MacOS, Linux, WSL:** `~/.cache/huggingface/hub/` * **Windows:** `%USERPROFILE%\.cache\huggingface\hub\` If `HF_HUB_CACHE` or `HF_HOME` is set, use that location instead. On Linux and WSL, `XDG_CACHE_HOME` can also change the default cache root. ### Using old / existing GGUF models {% columns %} {% column %} **Apr 1 update:** You can now select an existing folder for Unsloth to detect from. **Mar 27 update:** Unsloth Studio now **automatically detects older / pre-existing models** downloaded from Hugging Face, LM Studio etc. {% endcolumn %} {% column %}

{% endcolumn %} {% endcolumns %} **Manual instructions:** Unsloth Studio detects models downloaded to your Hugging Face Hub cache `(C:\Users{your_username}.cache\huggingface\hub)`. If you have GGUF models downloaded through LM Studio, note that these are stored in `C:\Users{your_username}.cache\lm-studio\models` ***OR*** `C:\Users{your_username}\lm-studio\models` . Sometimes when they are not visible, you will need to move or copy those .gguf files into your Hugging Face Hub cache directory (or another path accessible to llama.cpp) for Unsloth Studio to load them. After fine-tuning a model or adapter in Studio, you can export it to GGUF and run local inference with **llama.cpp** directly in Studio Chat. Unsloth Studio is powered by llama.cpp and Hugging Face. ### Google Colab notebook We’ve created a [free Google Colab notebook](https://colab.research.google.com/github/unslothai/unsloth/blob/main/studio/Unsloth_Studio_Colab.ipynb) so you can explore all of Unsloth’s features on Colab’s T4 GPUs. You can train and run most models up to 22B parameters, and switch to a larger GPU for bigger models. Just Click 'Run all' and the UI should pop up after installation. {% columns %} {% column %} {% embed url="" %} Once installation is complete, scroll to **Start Unsloth Studio** and click **Open Unsloth Studio** in the white box shown on the left: **Scroll further down, to see the actual UI.** {% endcolumn %} {% column %}

{% endcolumn %} {% endcolumns %} {% hint style="warning" %} Sometimes the Studio link may return an error. This happens because you might have disabled cookies or you're using an adblocker or Mozilla. You can still access the UI by scrolling below the button. Google Colab also expects you to stay on the Colab page; if it detects inactivity, it may shut down the GPU session. {% endhint %} ## Troubleshooting

Problem	Fix
Python version error	`sudo apt install python3.12 python3.12-venv` version 3.11 up to, but not including, 3.14
`nvidia-smi not found`	Install NVIDIA drivers from https://www.nvidia.com/Download/index.aspx
`nvcc not found` (CUDA)	`sudo apt install nvidia-cuda-toolkit` or add `/usr/local/cuda/bin` to PATH
llama-server build failed	Non-fatal, Studio still works, GGUF inference won't be available. Install `cmake` and re-run setup to fix.
`cmake not found`	`sudo apt install cmake`
`git not found`	`sudo apt install git`
Build failed	Delete `~/.unsloth/llama.cpp` and re-run setup

--- # Agent Instructions: 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: ``` GET https://unsloth.ai/docs/new/studio/install.md?ask= ``` The question should be specific, self-contained, and written in natural language. 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.