> 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/kuai-su-kai-shi/install/pip-install.md).

# 通过 pip 和 uv 安装 Unsloth

手动安装 Unsloth Studio，或使用 pip、uv 或虚拟环境安装 Unsloth Core。

**Unsloth 桌面版**, **Unsloth Studio**，以及 **Unsloth Core** 的安装方式不同。本页涵盖手动安装 Studio 和基于代码的 Core 包。

### Unsloth 桌面版

对于原生桌面应用，请使用操作系统下载，而不是下面的命令：

* <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** 是我们的网页界面。原生安装请参照下面：

{% 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" %}
The [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：**

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

更新 Unsloth：

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

{% endtab %}

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

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

更新 Unsloth：

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

{% endtab %}
{% endtabs %}

#### 启动：

{% columns %}
{% column %}
标准本地启动：

```bash
unsloth studio
```

有关安装和卸载的详细信息，请访问 [Unsloth Studio 安装](/docs/zh/xin/studio/install.md) 部分。
{% endcolumn %}

{% column %}
通过 HTTPS 安全地启动 Unsloth：

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

使用 [免费的 Cloudflare](/docs/zh/ji-chu-zhi-shi/ru-he-zai-ren-he-di-fang-ti-gong-ben-di-llm-fu-wu-shi-yong-cloudflare-he-unsloth-shi-xian-an-quan-yu.md) 隧道，在 Windows、Mac 或 Linux 上均可使用。
{% endcolumn %}
{% endcolumns %}

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

#### **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 桌面版**

要使用旧版 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：**&#x20;

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

**macOS、WSL、Linux：**

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

**Windows（PowerShell）：**

```ps1
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. 完全移除 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）：** 安装程序已将 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` 也可以更改默认缓存根目录。

## **Unsloth Core**

**使用以下命令安装 uv：**

**macOS、WSL、Linux：**

```shellscript
curl -LsSf https://astral.sh/uv/install.sh | sh
```

**Windows（PowerShell）：**

```powershell
irm https://astral.sh/uv/install.ps1 | iex
```

**使用 uv pip 安装 unsloth core（推荐），以获取最新的 pip 版本：**

```bash
uv venv unsloth_env --python 3.13
source unsloth_env/bin/activate
uv pip install unsloth --torch-backend=auto
```

或者仅用 pip：

```bash
pip install unsloth
```

要安装 **vLLM 和 Unsloth** 一起，请执行：

```bash
uv pip install unsloth vllm --torch-backend=auto
```

要安装 **最新主分支** 的 Unsloth，请执行：

{% code overflow="wrap" %}

```bash
uv pip install unsloth --torch-backend=auto
pip uninstall unsloth unsloth_zoo -y && pip install --no-deps git+https://github.com/unslothai/unsloth_zoo.git && pip install --no-deps git+https://github.com/unslothai/unsloth.git
```

{% endcode %}

对于 **venv 和虚拟环境安装** 为了将你的安装与系统包隔离，避免破坏系统包，并减少对系统造成不可修复的损害，请使用 venv：

{% code overflow="wrap" %}

```bash
apt install python3.10-venv python3.11-venv python3.12-venv python3.13-venv -y
python -m venv unsloth_env
source unsloth_env/bin/activate
pip install --upgrade pip && pip install uv
uv pip install unsloth --torch-backend=auto
```

{% endcode %}

如果你在 Jupyter、Colab 或其他笔记本中安装 Unsloth，请务必在命令前加上 `!`。在终端中使用时则不需要这样做

{% hint style="info" %}
现在已支持 Python 3.13！
{% endhint %}

### 卸载 Unsloth Core

如果你仍然遇到 Unsloth 的依赖问题，许多用户通过强制卸载并重新安装 Unsloth 解决了这些问题：

{% code overflow="wrap" %}

```bash
pip install --upgrade --force-reinstall --no-cache-dir --no-deps unsloth
pip install --upgrade --force-reinstall --no-cache-dir --no-deps unsloth_zoo
```

{% endcode %}

### 高级 Pip 安装

{% hint style="warning" %}
请 **勿** 在你有以下环境时使用此方法 [Conda](/docs/zh/kuai-su-kai-shi/install/conda-install.md).
{% endhint %}

由于存在依赖问题，Pip 会稍微复杂一些。对于 `torch 2.2、2.3、2.4、2.5` 和 CUDA 版本，pip 命令不同。

对于其他 torch 版本，我们支持 `torch211`, `torch212`, `torch220`, `torch230`, `torch240` 对于 CUDA 版本，我们支持 `cu118` 和 `cu121` 和 `cu124`。对于 Ampere 设备（A100、H100、RTX3090）及以上，请使用 `cu118-ampere` 或 `cu121-ampere` 或 `cu124-ampere`.

例如，如果你有 `torch 2.4` 和 `CUDA 12.1`，请使用：

```bash
pip install --upgrade pip
pip install "unsloth[cu121-torch240] @ git+https://github.com/unslothai/unsloth.git"
```

另一个例子，如果你有 `torch 2.5` 和 `CUDA 12.4`，请使用：

```bash
pip install --upgrade pip
pip install "unsloth[cu124-torch250] @ git+https://github.com/unslothai/unsloth.git"
```

还有其他示例：

```bash
pip install "unsloth[cu121-ampere-torch240] @ git+https://github.com/unslothai/unsloth.git"
pip install "unsloth[cu118-ampere-torch240] @ git+https://github.com/unslothai/unsloth.git"
pip install "unsloth[cu121-torch240] @ git+https://github.com/unslothai/unsloth.git"
pip install "unsloth[cu118-torch240] @ git+https://github.com/unslothai/unsloth.git"

pip install "unsloth[cu121-torch230] @ git+https://github.com/unslothai/unsloth.git"
pip install "unsloth[cu121-ampere-torch230] @ git+https://github.com/unslothai/unsloth.git"

pip install "unsloth[cu121-torch250] @ git+https://github.com/unslothai/unsloth.git"
pip install "unsloth[cu124-ampere-torch250] @ git+https://github.com/unslothai/unsloth.git"
```

或者，在终端中运行下面的命令以获取 **最优** pip 安装命令：

```bash
wget -qO- https://raw.githubusercontent.com/unslothai/unsloth/main/unsloth/_auto_install.py | python -
```

或者，在 Python REPL 中手动运行下面的内容：

{% code overflow="wrap" %}

```python
# 根据 Apache License, Version 2.0（“许可证”）授权
try: import torch
except: raise ImportError('通过 `pip install torch` 安装 torch')
from packaging.version import Version as V
import re
v = V(re.match(r"[0-9\.]{3,}", torch.__version__).group(0))
cuda = str(torch.version.cuda)
is_ampere = torch.cuda.get_device_capability()[0] >= 8
USE_ABI = torch._C._GLIBCXX_USE_CXX11_ABI
if cuda not in ("11.8", "12.1", "12.4", "12.6", "12.8", "13.0"): raise RuntimeError(f"不支持 CUDA = {cuda}！")
if   v <= V('2.1.0'): raise RuntimeError(f"Torch = {v} 太旧了！")
elif v <= V('2.1.1'): x = 'cu{}{}-torch211'
elif v <= V('2.1.2'): x = 'cu{}{}-torch212'
elif v  < V('2.3.0'): x = 'cu{}{}-torch220'
elif v  < V('2.4.0'): x = 'cu{}{}-torch230'
elif v  < V('2.5.0'): x = 'cu{}{}-torch240'
elif v  < V('2.5.1'): x = 'cu{}{}-torch250'
elif v <= V('2.5.1'): x = 'cu{}{}-torch251'
elif v  < V('2.7.0'): x = 'cu{}{}-torch260'
elif v  < V('2.7.9'): x = 'cu{}{}-torch270'
elif v  < V('2.8.0'): x = 'cu{}{}-torch271'
elif v  < V('2.8.9'): x = 'cu{}{}-torch280'
elif v  < V('2.9.1'): x = 'cu{}{}-torch290'
elif v  < V('2.9.2'): x = 'cu{}{}-torch291'
else: raise RuntimeError(f"Torch = {v} 太新了！")
if v > V('2.6.9') and cuda not in ("11.8", "12.6", "12.8", "13.0"): raise RuntimeError(f"不支持 CUDA = {cuda}！")
x = x.format(cuda.replace(".", ""), "-ampere" if False else "") # 由于 flash-attn，is_ampere 有问题
print(f'pip install --upgrade pip && pip install --no-deps git+https://github.com/unslothai/unsloth-zoo.git && pip install "unsloth[{x}] @ git+https://github.com/unslothai/unsloth.git" --no-build-isolation')
```

{% endcode %}


---

# 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/kuai-su-kai-shi/install/pip-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.