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

# 通过 pip 和 uv 安装 Unsloth

**Unsloth Desktop**, **Unsloth Studio**，以及 **Unsloth Core** 的安装方式不同。本页介绍手动安装 Studio 和基于代码的 Core 包。

### Unsloth Desktop

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

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

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

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

使用相同命令进行更新。

#### **Windows PowerShell：**

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

使用相同命令进行更新。

#### 启动：

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

有关详细的 Unsloth Studio 安装说明和要求， [查看我们的指南](/docs/zh/xin/studio/install.md).

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

#### **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）：**

```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 或其他 notebook 中安装 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/kai-shi-shi-yong/install/conda-install.md).
{% endhint %}

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

对于其他 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（“License”）许可
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 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/zh/kai-shi-shi-yong/install/pip-install.md?ask=<question>&goal=<endgoal>
```

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