> 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/new/studio/install.md). # 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 now works! * **CPU: Unsloth still works without a GPU**, but for Chat + Data Recipes. * **Training:** Works on **NVIDIA**: RTX 30, 40, 50, Blackwell, DGX Spark etc. + **Intel** + **AMD** GPUs ### 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 the same commands as install: **macOS, WSL, Linux:** ```bash curl -fsSL https://unsloth.ai/install.sh | sh ``` **Windows (PowerShell):** ```powershell 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) and training and all features. You can run MLX models with Unsloth. * macOS 12 Monterey or newer (Intel or Apple Silicon) * 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 / Nightly Installations (Advanced) ### **Main Repo Install** #### **macOS, Linux, WSL developer installs:** ```bash git clone https://github.com/unslothai/unsloth cd unsloth ./install.sh --local unsloth studio -p 8888 ``` To install into an isolated location (its own virtual env, `auth/`, `studio.db`, cache and llama.cpp build), set `UNSLOTH_STUDIO_HOME` and pass it again at launch: ```bash UNSLOTH_STUDIO_HOME="$PWD/.studio" ./install.sh --local UNSLOTH_STUDIO_HOME="$PWD/.studio" unsloth studio -p 8888 ``` Then to update : ```bash cd unsloth && git pull ./install.sh --local unsloth studio -p 8888 ``` #### **Windows PowerShell developer installs:** ```powershell git clone https://github.com/unslothai/unsloth.git cd unsloth Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass .\install.ps1 --local unsloth studio -p 8888 ``` To install into an isolated location (its own virtual env, `auth/`, `studio.db`, cache and llama.cpp build), set `UNSLOTH_STUDIO_HOME` and pass it again at launch: ```powershell $env:UNSLOTH_STUDIO_HOME="$PWD\.studio"; .\install.ps1 --local $env:UNSLOTH_STUDIO_HOME="$PWD\.studio"; unsloth studio -p 8888 ``` Then to update : ```powershell cd unsloth; git pull .\install.ps1 --local unsloth studio -p 8888 ``` #### **Remote access: `--secure` (HTTPS tunnel) vs raw port** By default `unsloth studio` binds to `127.0.0.1` (this machine only). To reach it from another device, pick one of: * `--secure` (recommended): serve **only** through a free Cloudflare HTTPS link. Studio stays bound to localhost and the tunnel provides the public URL; it fails closed (does not start) if the tunnel can't come up, so the raw port is never exposed. ```bash unsloth studio --secure -p 8888 ``` * `-H 0.0.0.0`: bind the raw port on all network interfaces, reachable from anywhere on the network. Only use this on a trusted network. ```bash unsloth studio -H 0.0.0.0 -p 8888 ``` Server-side tools (web search, Python and terminal code execution) run as your user and are on by default. Anyone who can reach the server with the API key can run code on this machine, so keep your API key private and pass `--disable-tools` when exposing Studio. ### Advanced Launch methods Installer options can be passed as environment variables. On macOS, Linux and WSL place the variable after the pipe so the shell passes it to `sh`; on Windows set it with `$env:` before piping to `iex`. Skip PyTorch (GGUF-only mode): ```bash curl -fsSL https://unsloth.ai/install.sh | UNSLOTH_NO_TORCH=1 sh ``` ```powershell $env:UNSLOTH_NO_TORCH=1; irm https://unsloth.ai/install.ps1 | iex ``` Pin the Python version: ```bash curl -fsSL https://unsloth.ai/install.sh | UNSLOTH_PYTHON=3.12 sh ``` ```powershell $env:UNSLOTH_PYTHON='3.12'; irm https://unsloth.ai/install.ps1 | iex ``` Install to a custom location with `UNSLOTH_STUDIO_HOME`: ```bash curl -fsSL https://unsloth.ai/install.sh | UNSLOTH_STUDIO_HOME=/abs/path sh ``` ```powershell $env:UNSLOTH_STUDIO_HOME='C:\path'; irm https://unsloth.ai/install.ps1 | iex ``` Cap Studio's native CPU thread pools on high-core hosts: `UNSLOTH_CPU_THREADS=8 unsloth studio -p 8888`. ### Uninstall The recommended way to fully remove Unsloth Studio is the matching uninstall script for your OS. It stops any running servers, removes the install dir, the launcher data dir, the desktop shortcut, and any platform-specific entries (macOS `.app` bundle + Launch Services on Mac; Start Menu, `HKCU\Software\Unsloth` registry key and user `PATH` entries on Windows): * **MacOS, WSL, Linux:** {% code overflow="wrap" expandable="true" %} ```bash curl -fsSL https://raw.githubusercontent.com/unslothai/unsloth/main/scripts/uninstall.sh | sh ``` {% endcode %} * **Windows (PowerShell):** {% code overflow="wrap" expandable="true" %} ```bash irm https://raw.githubusercontent.com/unslothai/unsloth/main/scripts/uninstall.ps1 | iex ``` {% endcode %} If you only want to drop the install dir and keep the launcher/shortcut for a later reinstall, you can instead run `rm -rf ~/.unsloth/studio` (Mac/Linux/WSL) or `Remove-Item -Recurse -Force "$HOME\.unsloth\studio"` (Windows). The model cache at `~/.cache/huggingface` is not touched by any of these. #### Manual uninstall If you prefer to remove only specific parts: **1. Remove app only** (keeps history, chats, checkpoints, and exports intact): * **macOS, WSL, Linux:** `rm -rf ~/.unsloth/studio/unsloth_studio` * **Windows (PowerShell):** `Remove-Item -Recurse -Force "$HOME\.unsloth\studio\unsloth_studio"` **2. Remove Studio entirely** (keeps other Unsloth tools intact): * **macOS, WSL, Linux:** `rm -rf ~/.unsloth/studio` * **Windows (PowerShell):** `Remove-Item -Recurse -Force "$HOME\.unsloth\studio"` **3. Remove everything Unsloth-related:** * **macOS, WSL, Linux:** `rm -rf ~/.unsloth` * **Windows (PowerShell):** `Remove-Item -Recurse -Force "$HOME\.unsloth"` {% hint style="warning" %} Note: Step 3 deletes everything in history, chats, model checkpoints, and exports. This cannot be undone. {% endhint %} **4. Remove shortcuts and symlinks:** **macOS:** ```shellscript rm -rf ~/Applications/Unsloth\ Studio.app ~/Desktop/Unsloth\ Studio ``` **Linux:** ```shellscript rm -f ~/.local/share/applications/unsloth-studio.desktop ~/Desktop/unsloth-studio.desktop ``` **WSL / Windows (PowerShell):** ```shellscript Remove-Item -Force "$HOME\Desktop\Unsloth Studio.lnk" Remove-Item -Force "$env:APPDATA\Microsoft\Windows\Start Menu\Programs\Unsloth Studio.lnk" ``` **5. Remove the CLI command:** * **macOS, Linux, WSL:** `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`. {% hint style="info" %} Note: Steps 1-5 dont touch your downloaded HF model files. See Deleting cached HF model files below if you want to reclaim that space. {% 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 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/new/studio/install.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.