# 通过 pip 和 uv 安装 Unsloth
Unsloth 可通过两种方式使用：通过 [Unsloth Studio](#unsloth-studio)，即 Web UI，或者通过 [Unsloth Core](#unsloth-core)，即基于代码的版本。
## **Unsloth Studio**
#### **MacOS、Linux、WSL：**
```bash
curl -fsSL https://unsloth.ai/install.sh | sh
```
使用相同命令进行更新，或者使用 `unsloth studio update`.
#### **Windows PowerShell：**
```bash
irm https://unsloth.ai/install.ps1 | iex
```
使用相同命令进行更新，或者使用 `unsloth studio update`.
#### 启动：
```bash
unsloth studio -H 0.0.0.0 -p 8888
```
有关 Unsloth Studio 的详细安装说明和要求， [查看我们的指南](https://unsloth.ai/docs/zh/xin/studio/install).
### **从主仓库安装**
#### **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
```
然后每次启动时：
unsloth studio -H 0.0.0.0 -p 8888
### 卸载
要卸载 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"`
这会删除应用程序，但会保留你的模型检查点、导出、历史记录、缓存和聊天内容。
#### **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"`
请注意，下载的 HF 模型文件会单独存储在 Hugging Face 缓存中——以上步骤不会删除它们。若想回收这些磁盘空间，请参见 **删除模型文件** 下方。
{% hint style="warning" %}
注意：使用 `rm -rf` 命令将会 **删除一切内容**，包括你的历史记录、缓存、聊天内容等。
{% endhint %}
### **删除缓存的 HF 模型文件**
你可以通过模型搜索中的垃圾桶图标删除旧模型文件，或者从默认的 Hugging Face 缓存目录中移除相关的缓存模型文件夹。默认情况下，Hugging Face 使用 `~/.cache/huggingface/hub/` 在 macOS/Linux/WSL 上，以及 `C:\Users\\.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 pip 安装（推荐），以获取最新的 pip 版本：**
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
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](https://unsloth.ai/docs/zh/kai-shi-shi-yong/install/conda-install).
{% 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（“许可证”）授权
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 %}