# Unsloth Studio 安装

Unsloth Studio 可在 Windows、Linux、WSL 和 MacOS 上运行。你应该在每台设备上使用相同的安装流程，不过系统要求可能因设备而异。

<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">开发者安装</a>

* **Mac：** 类似 CPU - [聊天](https://unsloth.ai/docs/zh/xin/chat#using-unsloth-studio-chat) + [数据配方](https://unsloth.ai/docs/zh/xin/studio/data-recipe) 目前可用。 **MLX** 训练即将很快推出。
* **CPU：Unsloth 在没有 GPU 的情况下仍可运行**，但仅适用于聊天 + 数据配方。
* **训练：** 可在以下设备上运行 **NVIDIA**：RTX 30、40、50、Blackwell、DGX Spark/Station 等 + **Intel** GPU
* **即将推出：** 支持 **Apple MLX** 和 **AMD**.

## 安装说明

请记住，各设备上的安装说明都是相同的：

{% stepper %}
{% step %}

#### 安装 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" %}
**由于使用了预编译的 llama.cpp 二进制文件，首次安装现在应快 6 倍，体积减少 50%。**
{% endhint %}

{% hint style="info" %}
**WSL 用户：** 系统会提示你输入 `sudo` 密码以安装构建依赖项（`cmake`, `git`, `libcurl4-openssl-dev`).
{% endhint %}
{% endstep %}

{% step %}

#### 启动 Unsloth Studio

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

<div data-with-frame="true"><figure><img src="https://2657992854-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>

**然后在浏览器中打开 `http://localhost:8888` 。**
{% endstep %}

{% step %}

#### 入门引导

首次启动时，你需要创建一个密码来保护你的账户，并可在稍后再次登录。随后你会看到一个简短的入门向导，用于选择模型、数据集和基本设置。你可以随时跳过。
{% endstep %}

{% step %}

#### 开始训练和运行

启动后立即开始微调和构建数据集。请查看我们的分步指南，快速上手 Unsloth Studio：

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

### 更新 Unsloth Studio：

要更新 Unsloth Studio，请使用：

{% code overflow="wrap" %}

```bash
unsloth studio update 
```

{% endcode %}

如果那不起作用，你可以使用下面的方法：

#### **MacOS、Linux、WSL：**

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

#### **Windows PowerShell：**

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

## 系统要求

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

Unsloth Studio 可直接在 Windows 上运行，无需 WSL。要训练模型，请确保你的系统满足以下要求：

**要求**

* Windows 10 或 Windows 11（64 位）
* 已安装驱动程序的 NVIDIA GPU
* **应用安装程序** （包括 `winget`): [此处](https://learn.microsoft.com/en-us/windows/msix/app-installer/install-update-app-installer)
* **Git**: `winget install --id Git.Git -e --source winget`
* **Python**：版本 3.11 至 3.14 之前（不含 3.14）
* 在 Python 环境中工作，例如 **uv**, **venv**，或 **conda/mamba**

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

Unsloth Studio 可在 Mac 设备上运行，用于 [聊天](#run-models-locally) 适用于 GGUF 模型和 [数据配方](https://unsloth.ai/docs/zh/xin/studio/data-recipe) ([导出](https://unsloth.ai/docs/zh/xin/studio/export) （即将很快推出）。 **MLX 训练即将推出！**

* macOS 12 Monterey 或更新版本（Intel 或 Apple Silicon）
* 安装 Homebrew： [此处](https://brew.sh/)
* Git： `brew install git`&#x20;
* cmake： `brew install cmake`&#x20;
* openssl： `brew install openssl`
* Python：版本 3.11 至 3.14 之前（不含 3.14）
* 在 Python 环境中工作，例如 **uv**, **venv**，或 **conda/mamba**

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

* Ubuntu 20.04+ 或类似发行版（64 位）
* 已安装驱动程序的 NVIDIA GPU
* CUDA 工具包（推荐 12.4+，Blackwell 推荐 12.8+）
* Git： `sudo apt install git`
* Python：版本 3.11 至 3.14 之前（不含 3.14）
* 在 Python 环境中工作，例如 **uv**, **venv**，或 **conda/mamba**

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

{% hint style="success" %}
我们的 Docker 镜像现在可用于 Studio！我们正在努力兼容 Mac。
{% endhint %}

* 拉取我们最新的 Unsloth 容器镜像： `docker pull unsloth/unsloth`
* 通过以下命令运行容器：

```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
```

更多信息， [请见此处](https://hub.docker.com/r/unsloth/unsloth#unsloth-docker-image).

* 访问你的 studio 实例： `http://localhost:8000` 或外部 IP 地址 `http://external_ip_address:8000/`

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

Unsloth Studio 支持 CPU 设备用于 [聊天](#run-models-locally) 适用于 GGUF 模型和 [数据配方](https://unsloth.ai/docs/zh/xin/studio/data-recipe) ([导出](https://unsloth.ai/docs/zh/xin/studio/export) （即将很快推出）

* 与上面提到的 Linux 相同（不包括 NVIDIA GPU 驱动）以及 MacOS。

## 开发者安装（高级）

### **从主仓库安装**

#### **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
```

#### **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
```

### **夜间版安装**

#### **夜间版 - MacOS、Linux、WSL：**

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

然后每次启动都执行：

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

#### **夜间版 - Windows：**

在 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
```

然后每次启动都执行：

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

### 卸载

要卸载 Unsloth Studio，请按以下 4 个步骤操作：

#### **1. 删除应用程序**

* 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;

这会删除应用程序，但会保留你的模型检查点、导出、历史记录、缓存和聊天内容。

#### **2. 删除快捷方式和符号链接**

**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. 删除 CLI 命令**

**macOS、Linux、WSL：**

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

**Windows（PowerShell）：** 安装程序已将 venv 的 `Scripts` 目录添加到你的用户 PATH 中。若要删除它，请打开 设置 → 系统 → 关于 → 高级系统设置 → 环境变量，找到 `Path` 在用户变量下，并删除指向 `.unsloth\studio\...\Scripts`.

#### **4. 删除所有内容（可选）**

如果你还想删除历史记录、缓存、聊天、模型检查点和模型导出，请删除整个 Unsloth 文件夹：

* MacOS、WSL、Linux： `rm -rf ~/.unsloth`
* Windows（PowerShell）： `Remove-Item -Recurse -Force "$HOME\.unsloth"`&#x20;

请注意，下载的 HF 模型文件是单独存储在 Hugging Face 缓存中的——上述步骤都不会删除它们。请参见 **删除模型文件** 如果你想释放这些磁盘空间，请见下文。

{% hint style="warning" %}
注意：使用 `rm -rf` 命令将会 **删除一切**，包括你的历史记录、缓存、聊天等。
{% endhint %}

### **删除缓存的 HF 模型文件**

你可以通过模型搜索中的垃圾桶图标删除旧模型文件，或从默认的 Hugging Face 缓存目录中移除相关的缓存模型文件夹。默认情况下，Hugging Face 使用 `~/.cache/huggingface/hub/` 在 macOS/Linux/WSL 上，以及 `C:\Users\<username>\.cache\huggingface\hub\` 在 Windows 上。

* **MacOS、Linux、WSL：** `~/.cache/huggingface/hub/`
* **Windows：** `%USERPROFILE%\.cache\huggingface\hub\`

如果 `HF_HUB_CACHE` 或 `HF_HOME` 已设置，请改用该位置。在 Linux 和 WSL 上， `XDG_CACHE_HOME` 也可以更改默认缓存根目录。

### 使用旧的 / 现有的 GGUF 模型

{% columns %}
{% column %}
**4 月 1 日更新：** 你现在可以选择一个现有文件夹，让 Unsloth 从中检测。

**3 月 27 日更新：** Unsloth Studio 现在 **可自动检测较旧 / 预先存在的模型** ，这些模型可从 Hugging Face、LM Studio 等处下载。
{% endcolumn %}

{% column %}

<figure><img src="https://2657992854-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 %}

**手动说明：** Unsloth Studio 会检测下载到你的 Hugging Face Hub 缓存中的模型 `(C:\Users{your_username}.cache\huggingface\hub)`。如果你通过 LM Studio 下载了 GGUF 模型，请注意这些模型存储在 `C:\Users{your_username}.cache\lm-studio\models` ***或*** `C:\Users{your_username}\lm-studio\models` 。有时当它们不可见时，你需要将这些 .gguf 文件移动或复制到你的 Hugging Face Hub 缓存目录（或 llama.cpp 可访问的其他路径）中，Unsloth Studio 才能加载它们。

在 Studio 中微调模型或适配器后，你可以将其导出为 GGUF，并在 Studio Chat 中直接使用 **llama.cpp** 进行本地推理。Unsloth Studio 由 llama.cpp 和 Hugging Face 提供支持。

### <i class="fa-google">:google:</i> Google Colab 笔记本

我们创建了一个 [免费的 Google Colab 笔记本](https://colab.research.google.com/github/unslothai/unsloth/blob/main/studio/Unsloth_Studio_Colab.ipynb) ，这样你就可以在 Colab 的 T4 GPU 上探索 Unsloth 的所有功能。你可以训练并运行大多数参数量高达 22B 的模型，并切换到更大的 GPU 来运行更大的模型。只需点击“Run all”，安装后界面应该会弹出。

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

安装完成后，向下滚动到 **启动 Unsloth Studio** 并点击 **打开 Unsloth Studio** ，位于左侧显示的白色框中：

**继续向下滚动，即可看到实际界面。**
{% endcolumn %}

{% column %}

<div data-with-frame="true"><figure><img src="https://2657992854-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" %}
有时 Studio 链接可能会返回错误。这是因为你可能禁用了 Cookie，或者你正在使用广告拦截器或 Mozilla。你仍然可以通过向下滚动到按钮下方来访问界面。

Google Colab 还要求你留在 Colab 页面上；如果检测到不活动，它可能会关闭 GPU 会话。
{% endhint %}

## 故障排除

<table><thead><tr><th width="211.5999755859375">问题</th><th>修复</th></tr></thead><tbody><tr><td>Python 版本错误</td><td><code>sudo apt install python3.12 python3.12-venv</code> 版本 3.11 至 3.14 之前（不含 3.14）</td></tr><tr><td><code>找不到 nvidia-smi</code></td><td>从 https://www.nvidia.com/Download/index.aspx 安装 NVIDIA 驱动程序</td></tr><tr><td><code>找不到 nvcc</code> （CUDA）</td><td><code>sudo apt install nvidia-cuda-toolkit</code> 或将 <code>/usr/local/cuda/bin</code> 添加到 PATH</td></tr><tr><td>llama-server 构建失败</td><td>非致命错误，Studio 仍可工作，但无法使用 GGUF 推理。安装 <code>cmake</code> 并重新运行设置即可修复。</td></tr><tr><td><code>找不到 cmake</code></td><td><code>sudo apt install cmake</code></td></tr><tr><td><code>找不到 git</code></td><td><code>sudo apt install git</code></td></tr><tr><td>构建失败</td><td>删除 <code>~/.unsloth/llama.cpp</code> 并重新运行设置</td></tr></tbody></table>