> 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 可在 Windows、Linux、WSL 和 MacOS 上运行。你应在每台设备上使用相同的安装流程，尽管系统要求可能因设备而异。

<a href="/pages/ef666f465ed5ec55124d17ba90cfb169b4efa95f#windows" class="button secondary" data-icon="windows">Windows</a><a href="/pages/ef666f465ed5ec55124d17ba90cfb169b4efa95f#macos" class="button secondary" data-icon="apple">MacOS</a><a href="/pages/ef666f465ed5ec55124d17ba90cfb169b4efa95f#linux-wsl" class="button secondary" data-icon="linux">Linux 和 WSL</a><a href="/pages/ef666f465ed5ec55124d17ba90cfb169b4efa95f#docker" class="button secondary" data-icon="docker">Docker</a><a href="/pages/ef666f465ed5ec55124d17ba90cfb169b4efa95f#developer-installation-advanced" class="button secondary" data-icon="screwdriver-wrench">开发者安装</a>

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

### 快速开始

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

#### 步骤 1：设置 Unsloth

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

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

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

<figure><img src="/files/5f519c6be67e8e04d146b8890e77a97ea1d57b24" alt="" width="375"><figcaption></figcaption></figure>

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

#### 步骤 2：启动 Unsloth

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

<figure><img src="/files/3b5e738d6fe20d5b532b5938e5a1110a6a2d382b" alt="" width="375"><figcaption></figcaption></figure>

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

{% 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="/files/5f519c6be67e8e04d146b8890e77a97ea1d57b24" 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="/files/752cee75840c3ad7dcf1d7c341a194e63895ac0e" alt="" width="375"><figcaption></figcaption></figure>

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

{% 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`，或者搜索 `Terminal` 在系统的应用菜单中。
{% 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` 当系统询问是否允许 Studio 现在启动时。这将把 Unsloth 启动在你的本地 **8888** 端口上。

<figure><img src="/files/6f5baa1b6cb53a7720aa0f8a23166f0ba32cb456" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
如果你在安装过程中选择不启动 Unsloth，也可以随时使用 `unsloth studio -p 8888` 启动 Unsloth 应用。如果你希望 PC/电脑外部的客户端也能访问你的 Unsloth 实例，请添加 `-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="/files/ece9f13878a0bc547e2f0e7b1e6e5621bdd6329a" alt="" width="563"><figcaption></figcaption></figure>

在 `新密码` 字段中输入新密码，并在 `确认密码` 中重新输入相同密码，然后点击 **更改密码** 按&#x94AE;**.**

<figure><img src="/files/0f3b1da58479df6e434a9858d7905099bfe6b79d" alt="" width="158"><figcaption></figcaption></figure>

Unsloth 应用现在应会在聊天页面打开，如图所示。 **Unsloth Studio** 现已安装并可使用。

<figure><img src="/files/7b2ae9fdc1091c21ec8c93b895ed3c97c9326dab" alt="" width="563"><figcaption></figcaption></figure>

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

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

### 更新 Unsloth Studio

要更新 Unsloth Studio，请使用与安装相同的命令：

**macOS、WSL、Linux：**

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

**Windows（PowerShell）：**

```powershell
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
* **App Installer** （包含 `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) 用于 GGUF 模型和 [数据配方](/docs/zh/xin/studio/data-recipe.md) ([导出](/docs/zh/xin/studio/export.md) 即将推出）。 **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 之前
* 在 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 之前
* 在 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 模型和 [数据配方](/docs/zh/xin/studio/data-recipe.md) ([导出](/docs/zh/xin/studio/export.md) 即将推出）

* 与上面 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 的推荐方式是使用你操作系统对应的卸载脚本。它会停止所有正在运行的服务器，移除应用、CLI 命令、启动器数据、快捷方式以及平台特定条目（macOS `.app` 捆绑包 + Launch Services；Windows 开始菜单 + 注册表 + PATH）：

**macOS、WSL、Linux：**

```shellscript
curl -fsSL https://raw.githubusercontent.com/unslothai/unsloth/main/scripts/uninstall.sh | sh
```

**Windows（PowerShell）：**

```powershell
irm https://raw.githubusercontent.com/unslothai/unsloth/main/scripts/uninstall.ps1 | iex 
```

#### 手动卸载

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

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

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

**2. 完全移除 Studio** （保留其他 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）：** 安装程序已将 venv 的 `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="/files/cec2e46a923f32a71170420c00c39d7df4a8dbf4" 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，并使用 **llama.cpp** 直接在 Studio 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="/files/23d7b9394cb33ccc206be2027b143e6290680aea" alt=""><figcaption></figcaption></figure></div>
{% endcolumn %}
{% endcolumns %}

{% hint style="warning" %}
有时 Studio 链接可能会返回错误。这是因为你可能禁用了 cookies，或者你在使用广告拦截器或 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>非致命错误，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>


---

# 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:

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

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.