> 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/zh/xin/studio/install.md).

# Unsloth Studio 安装

手动安装 Unsloth Studio，或下载独立的 Unsloth Desktop 应用。

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

### 使用 Unsloth Desktop 安装

安装 Unsloth Studio 最简单的方法是使用原生 [桌面应用](/docs/zh/desktop.md)。请为你的操作系统下载：

* <i class="fa-apple">:apple:</i> [下载 macOS 版](https://unsloth.ai/download/mac)
* <i class="fa-windows">:windows:</i> [下载 Windows 版](https://unsloth.ai/download/windows)
* <i class="fa-linux">:linux:</i> [下载 Linux 版](https://unsloth.ai/download/linux)

本页其余部分将 **Unsloth Studio** 手动安装。

### Unsloth Studio 手动安装

<a href="https://unsloth.ai/docs/new/studio/install#windows-1" class="button secondary" data-icon="windows">Windows</a><a href="https://unsloth.ai/docs/new/studio/install#macos-1" class="button secondary" data-icon="apple">macOS</a><a href="https://unsloth.ai/docs/new/studio/install#linux-and-wsl" class="button secondary medium" data-icon="linux">Linux 和 WSL</a><a href="/docs/zh/xin/studio/install.md#docker" class="button secondary" data-icon="docker">Docker</a><a href="https://unsloth.ai/docs/new/studio/install#developer-nightly-installations-advanced" class="button secondary" data-icon="screwdriver-wrench">开发者安装</a>

### 快速开始

{% tabs %}
{% tab title="macOS、Linux、WSL" %}
**安装 Unsloth：**

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

使用相同的命令进行更新。
{% endtab %}

{% tab title="Windows" %}
**安装 Unsloth：**

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

使用相同的命令进行更新。
{% endtab %}

{% tab title="Docker" %}
该 [Unsloth Docker 镜像](https://hub.docker.com/r/unsloth/unsloth) `unsloth/unsloth` 可在 Docker 上获取。 [阅读指南。](https://unsloth.ai/docs/get-started/install/docker)
{% endtab %}

{% tab title="Homebrew" %}
安装 Unsloth Desktop：

{% code collapsedlinecount="10" %}

```bash
brew install --cask unsloth
```

{% endcode %}

更新 Unsloth Desktop：

```bash
brew upgrade --cask unsloth
```

{% endtab %}

{% tab title="WinGet" %}
安装 Unsloth Desktop：

```powershell
winget install --id UnslothAI.Unsloth -e
```

更新 Unsloth Desktop：

```powershell
winget upgrade --id UnslothAI.Unsloth -e
```

{% endtab %}
{% endtabs %}

下面请查看更详细的分步说明：

{% tabs %}
{% tab title="macOS" %}

#### 步骤 1：设置 Unsloth

启动 `终端` 来自 Mac，然后输入下面的命令来安装 Unsloth。

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

或使用 **Homebrew**:

```bash
brew install --cask unsloth
```

Unsloth 将开始设置环境并安装所需的软件包，如下所示。输入 **Y** 并按 `Enter` ，当系统询问你是否要立即允许 Unsloth 启动时。这样会在你的本地 **8888** 端口上启动 Unsloth。

<figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FnKjv9Qn86NpTc0jIAANL%2FStart_studio_windows_powershell.png?alt=media&amp;token=be7dfb36-80a9-4a5d-bcf6-063a887a471e" alt="" width="375"><figcaption></figcaption></figure>

{% hint style="info" %}
如果你在安装过程中选择不启动 Unsloth，你随时都可以使用以下命令启动 Unsloth 应用： `unsloth studio -p 8888` 。如果你希望你的 Unsloth 实例可供 PC/电脑外部的客户端访问，请添加 `-H 0.0.0.0` 到 `unsloth studio` 命令中。
{% endhint %}

#### 步骤 2：启动 Unsloth

打开你常用的浏览器并访问 `http://127.0.0.1:8888` URL。如果这是你第一次安装 Unsloth，系统会提示你创建一个新密码。之后，Unsloth 应用应会如下所示在聊天页面打开。

<figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FNX8VzAre3aWM86uUz9U6%2Fimage.png?alt=media&amp;token=7eccde46-6188-48a5-95de-05f0e8bf44be" alt="" width="375"><figcaption></figcaption></figure>

**使用 HTTPS 和 Cloudflare 安全启动 Unsloth。** Unsloth 现在提供了一种通过免费的 Cloudflare 隧道以 HTTPS 安全启动 Unsloth 的方式。使用下面的命令（适用于 Windows、Mac 和 Linux）：

```bash
unsloth studio --secure
```

你可以立即开始训练和运行模型。下面你可以查看我们更详细的分步入门指南：

{% content-ref url="/pages/12f6b822ad28322267b74accad74f665b341f5a4" %}
[Get Started](/docs/zh/xin/studio/start.md)
{% endcontent-ref %}
{% endtab %}

{% tab title="Windows" %}

#### 步骤 1：设置 Unsloth

打开开始菜单，搜索 `PowerShell`，然后启动它。复制并粘贴下面的安装命令：

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

它将自动开始安装。安装完成后，PowerShell 会询问你是否要启动 Unsloth Studi&#x6F;**.**

<figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FnKjv9Qn86NpTc0jIAANL%2FStart_studio_windows_powershell.png?alt=media&amp;token=be7dfb36-80a9-4a5d-bcf6-063a887a471e" alt="" width="375"><figcaption></figcaption></figure>

你也可以使用以下命令启动它：

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

{% hint style="info" %}
如果你希望你的实例可供 PC/电脑外部的客户端访问。\
添加 `-H 0.0.0.0` 到 `unsloth studio` 命令中。
{% endhint %}

#### 步骤 2：启动 Unsloth

在浏览器中打开 `http://127.0.0.1:8888` 。首次启动时，请创建一个新密码以继续进入聊天页面。 **Unsloth Studio** 现已安装并可使用。

Unsloth 应用应会如下所示在聊天页面打开。

<figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FtQZliTMxnBZcJSAidbOc%2Fimage.png?alt=media&amp;token=df1e9734-b7ba-448d-b600-1025035527ca" alt="" width="375"><figcaption></figcaption></figure>

**使用 HTTPS 和 Cloudflare 安全启动 Unsloth。** Unsloth 现在提供了一种通过免费的 Cloudflare 隧道以 HTTPS 安全启动 Unsloth 的方式。使用下面的命令（适用于 Windows、Mac 和 Linux）：

```bash
unsloth studio --secure
```

你可以立即开始训练和运行模型。下面你可以查看我们更详细的分步入门指南：

{% content-ref url="/pages/12f6b822ad28322267b74accad74f665b341f5a4" %}
[Get Started](/docs/zh/xin/studio/start.md)
{% endcontent-ref %}
{% endtab %}

{% tab title="Linux、WSL" %}

#### 步骤 1：设置 Unsloth

{% tabs %}
{% tab title="Linux" %}
打开你的终端应用。你可以通过按 `Ctrl + Alt + T`，或者搜索 `终端` 在你系统的应用菜单中打开它。
{% endtab %}

{% tab title="WSL" %}
点击 Windows 开始菜单，输入你已安装发行版的名称（例如 `Ubuntu`），然后打开它。

{% hint style="warning" %}
在 **WSL**上，确保你的 **NVIDIA 驱动程序** 已安装在 **Windows** 上（不在 WSL 内），并且 **CUDA 工具包** 已安装在你的 WSL 发行版中。有关详细信息，请参阅下面的系统要求。
{% endhint %}
{% endtab %}
{% endtabs %}

要安装，请复制并运行安装命令：

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

然后：

1. 点击终端窗口内部
2. 使用 `Ctrl + Shift + V`
3. 按 `Enter`

Unsloth 将开始设置环境并安装所需的软件包，如下所示。输入 **Y** 并按 `Enter` ，当系统询问你是否要立即允许 Unsloth 启动时。这样会在你的本地 **8888** 端口上启动 Unsloth。

<figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FaCUj9vIsSLtxrrRZ4UVx%2Fimage.png?alt=media&amp;token=27f413dd-65b2-4312-b344-506919bccc6c" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
如果你在安装过程中选择不启动 Unsloth，你随时都可以使用以下命令启动 Unsloth 应用： `unsloth studio -p 8888` 。如果你希望你的 Unsloth 实例可供 PC/电脑外部的客户端访问，请添加 `-H 0.0.0.0` 到 `unsloth studio` 命令中。
{% endhint %}

#### 步骤 2：启动 Unsloth

打开你常用的浏览器并输入 `http://127.0.0.1:8888` 在 URL 框中。如果这是你第一次安装 Unsloth，你将被转到 `http://127.0.0.1:8888/change-password` 页面，如下所示：

<figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FnM9s9317lNmCQVJugLDU%2Fimage.png?alt=media&amp;token=740cb99d-23ab-4767-bfa2-41f49769d96d" alt="" width="563"><figcaption></figcaption></figure>

**使用 HTTPS 和 Cloudflare 安全启动 Unsloth。** Unsloth 现在提供了一种通过免费的 Cloudflare 隧道以 HTTPS 安全启动 Unsloth 的方式。使用下面的命令（适用于 Windows、Mac 和 Linux）：

```bash
unsloth studio --secure
```

你可以立即开始训练和运行模型。下面你可以查看我们更详细的分步入门指南：

{% content-ref url="/pages/12f6b822ad28322267b74accad74f665b341f5a4" %}
[Get Started](/docs/zh/xin/studio/start.md)
{% endcontent-ref %}
{% endtab %}
{% endtabs %}

## 系统要求

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

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

**要求**

* Windows 10 或 Windows 11（64 位）
* 已安装驱动程序的 NVIDIA GPU（对于 Intel GPU，请参阅 [Intel GPU](#intel-gpus))
* **应用安装程序** （包含 `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 之前
* 在 Python 环境中工作，例如 **uv**, **venv**，或 **conda/mamba**

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

Unsloth Studio 可在 Mac 设备上用于 [聊天](#run-models-locally) 以及训练和所有功能。你可以使用 Unsloth 运行 MLX 模型。

* macOS 12 Monterey 或更新版本（Intel 或 Apple Silicon）
* 在 Python 环境中工作，例如 **uv**, **venv**，或 **conda/mamba**

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

* Ubuntu 20.04+ 或类似发行版（64 位）
* 已安装驱动程序的 NVIDIA GPU（对于 Intel GPU，请参阅 [Intel GPU](#intel-gpus))
* CUDA 工具包（建议 12.4+，blackwell 需要 12.8+）
* Git： `sudo apt install git`
* Python：版本 3.11 起，到 3.14 之前
* 在 Python 环境中工作，例如 **uv**, **venv**，或 **conda/mamba**

### <i class="fa-microchip">:microchip:</i> Intel GPU

先安装最新的 Intel GPU 驱动程序（请参阅我们的 [Intel 指南](/docs/zh/kuai-su-kai-shi/install/intel.md)）。当安装程序检测到的唯一 GPU 是 Intel Arc、Arc Pro、带 Arc 显卡的 Core Ultra，或 Data Center GPU Max / Flex 时，它会在 Linux 和 Windows 上自动选择 Intel XPU PyTorch。在 Linux 上，当发生这种情况时，安装程序的 GPU 行会显示 `Intel GPU（<device id>，XPU）` 。

当安装程序无法看到或选择 Intel GPU 时，请手动固定 XPU PyTorch：

* **WSL**，此时安装程序看不到任何 PCI 显示设备
* 一个也有 NVIDIA 或 AMD GPU 的系统（一次 PyTorch 安装只支持一个厂商，因此另一个 GPU 将不会用于训练）
* 在 Linux 上， `ONEAPI_DEVICE_SELECTOR`, `SYCL_DEVICE_FILTER` 或 `SYCL_DEVICE_ALLOWLIST` 被设置，或者 `ZE_AFFINITY_MASK` 被设置为除空值或 `默认`

**Linux、WSL：**

{% code collapsedlinecount="10" %}

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

# 或使用完整索引 URL
curl -fsSL https://unsloth.ai/install.sh | UNSLOTH_TORCH_INDEX_URL=https://download.pytorch.org/whl/xpu sh
```

{% endcode %}

**Windows（PowerShell）：**

{% code collapsedlinecount="10" %}

```powershell
$env:UNSLOTH_TORCH_INDEX_FAMILY = "xpu"; irm https://unsloth.ai/install.ps1 | iex
```

{% endcode %}

如果你已固定 XPU（例如在 WSL 上），每次重新运行安装程序进行更新时都要设置相同变量；如果不设置，重新运行会再次安装 CPU PyTorch。要在带有 Intel GPU 的系统上保持使用 CPU PyTorch，请改为设置 `UNSLOTH_TORCH_INDEX_FAMILY=cpu` （或者 `UNSLOTH_DISABLE_XPU_AUTO=1` 在 Linux 上）。

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

{% hint style="success" %}
我们的 Docker 镜像现在可用于 Unsloth！我们正在努力支持 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 模型和 [数据配方](/docs/zh/xin/studio/data-recipe.md)

* 与上面 Linux 所述相同（除了 NVIDIA GPU 驱动程序）和 MacOS。

## 开发者 / 夜间构建安装（高级）

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

#### **macOS、Linux、WSL 开发者安装：**

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

若要安装到隔离位置（其自己的虚拟环境、 `auth/`, `studio.db`、缓存和 llama.cpp 构建），请设置 `UNSLOTH_STUDIO_HOME` 并在启动时再次传入：

```bash
UNSLOTH_STUDIO_HOME="$PWD/.studio" ./install.sh --local
UNSLOTH_STUDIO_HOME="$PWD/.studio" unsloth studio -p 8888
```

然后更新：

```bash
cd unsloth && git pull
./install.sh --local
unsloth studio -p 8888
```

#### **Windows PowerShell 开发者安装：**

```powershell
git clone https://github.com/unslothai/unsloth.git
cd unsloth
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
.\install.ps1 --local
unsloth studio -p 8888
```

若要安装到隔离位置（其自己的虚拟环境、 `auth/`, `studio.db`、缓存和 llama.cpp 构建），请设置 `UNSLOTH_STUDIO_HOME` 并在启动时再次传入：

```powershell
$env:UNSLOTH_STUDIO_HOME="$PWD\.studio"; .\install.ps1 --local
$env:UNSLOTH_STUDIO_HOME="$PWD\.studio"; unsloth studio -p 8888
```

然后更新：

```powershell
cd unsloth; git pull
.\install.ps1 --local
unsloth studio -p 8888
```

#### **远程访问： `--secure` （HTTPS 隧道）与原始端口**

默认情况下 `unsloth studio` 绑定到 `127.0.0.1` （仅本机）。要从其他设备访问，请选择以下之一：

* `--secure` （推荐）：通过 **仅** 免费的 Cloudflare HTTPS 链接提供服务。Unsloth 仍绑定到 localhost，而隧道提供公共 URL；如果隧道无法建立，它会失败并关闭（不会启动），因此原始端口绝不会暴露。

```bash
unsloth studio --secure -p 8888
```

* `-H 0.0.0.0`：在所有网络接口上绑定原始端口，可从网络中的任何位置访问。仅在受信任的网络中使用。

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

服务器端工具（网页搜索、Python 和终端代码执行）以你的用户身份运行，且默认开启。任何能够使用 API 密钥访问服务器的人都可以在此机器上运行代码，因此请妥善保管你的 API 密钥并传入 `--disable-tools` ，当你暴露 Unsloth 时。

### 高级启动方式

安装程序选项可以通过环境变量传入。在 macOS、Linux 和 WSL 上，将变量放在管道符号后面，以便 shell 将其传递给 `sh`；在 Windows 上，用 `$env:` 在管道传给之前设置它 `iex`.

跳过 PyTorch（仅 GGUF 模式）：

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

固定 Python 版本：

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

使用以下方式安装到自定义位置 `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
```

在高核数主机上限制 Unsloth 原生 CPU 线程池： `UNSLOTH_CPU_THREADS=8 unsloth studio -p 8888`.

### **使用旧版本**

#### **Unsloth Desktop**

若要使用旧版本的 Unsloth Desktop，非常简单。只需查看 [我们的 GitHub 发布](https://github.com/unslothai/unsloth/releases) 并在 'Assets' 区域中选择你想安装的特定版本。

#### **Unsloth Studio**

若要使用旧版本的 Unsloth Studio，请按下面内容，并使用你想要的版本和名称：

**macOS、Linux、WSL：**

```shellscript
uv pip install \
  --python "$HOME/.unsloth/studio/unsloth_studio/bin/python" \
  --reinstall --no-deps "unsloth==VERSION"

"$HOME/.unsloth/studio/unsloth_studio/bin/unsloth" studio -p 8888
```

**Windows：**

```shellscript
uv pip install `
  --python "$env:USERPROFILE\.unsloth\studio\unsloth_studio\Scripts\python.exe" `
  --reinstall --no-deps "unsloth==VERSION"

& "$env:USERPROFILE\.unsloth\studio\unsloth_studio\Scripts\unsloth.exe" studio -p 8888
```

### 卸载

完全移除 Unsloth Studio 的推荐方式是使用与你的操作系统匹配的卸载脚本。它会停止任何正在运行的服务器，移除安装目录、启动器数据目录、桌面快捷方式，以及任何平台特定条目（Mac 上的 macOS `.app` 包 + Mac 上的 Launch Services；开始菜单， `HKCU\Software\Unsloth` 注册表项和用户 `PATH` 条目（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 %}

如果你只想删除安装目录并保留启动器/快捷方式以便以后重新安装，你也可以运行 `rm -rf ~/.unsloth/studio` （Mac/Linux/WSL）或 `Remove-Item -Recurse -Force "$HOME\.unsloth\studio"` （Windows）。位于 `~/.cache/huggingface` 的模型缓存不会被这些操作影响。

#### 手动卸载

如果你只想移除特定部分：

**1. 仅移除应用** （保留历史记录、聊天、检查点和导出）：

* **macOS、WSL、Linux：** `rm -rf ~/.unsloth/studio/unsloth_studio`
* **Windows（PowerShell）：** `Remove-Item -Recurse -Force "$HOME\.unsloth\studio\unsloth_studio"`

**2. 完全移除 Unsloth** （保留其他 Unsloth 工具）：

* **macOS、WSL、Linux：** `rm -rf ~/.unsloth/studio`
* **Windows（PowerShell）：** `Remove-Item -Recurse -Force "$HOME\.unsloth\studio"`

**3. 移除所有与 Unsloth 相关的内容：**

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

{% hint style="warning" %}
注意：第 3 步会删除历史记录、聊天、模型检查点和导出中的所有内容。这无法撤销。
{% endhint %}

**4. 删除快捷方式和符号链接：**

**macOS：**

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

**Linux：**&#x20;

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

* **macOS、Linux、WSL：** `rm -f ~/.local/bin/unsloth`
* **Windows（PowerShell）：** 安装程序已将虚拟环境的 `Scripts` 目录添加到了你的用户 PATH。要移除它，请打开 设置 → 系统 → 关于 → 高级系统设置 → 环境变量，找到 `Path` 在用户变量下，并删除指向 `.unsloth\studio\...\Scripts`.

{% hint style="info" %}
注意：第 1-5 步不会触碰你已下载的 HF 模型文件。如果你想回收那部分空间，请参见下面删除已缓存 HF 模型文件。
{% 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&amp;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 才能加载它们。

在 Unsloth 中对模型或适配器进行微调后，您可以将其导出为 GGUF，并使用 **llama.cpp** 直接在 Unsloth Chat 中运行本地推理。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&amp;token=4388c309-a598-41f3-9301-e434c334ac1c" alt=""><figcaption></figcaption></figure></div>
{% endcolumn %}
{% endcolumns %}

{% hint style="warning" %}
有时 Unsloth 链接可能会返回错误。这是因为您可能禁用了 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</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>非致命错误，Unsloth 仍可正常工作，但将无法使用 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>


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://unsloth.ai/docs/zh/xin/studio/install.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.