通过 pip 和 uv 安装 Unsloth

要通过 Pip 在本地安装 Unsloth，请按照以下步骤操作：

Unsloth 可通过两种方式使用：通过 Unsloth Studio，即网页 UI，或者通过 Unsloth Core，即基于代码的版本。

Unsloth Studio

MacOS、Linux、WSL：

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

使用相同的命令进行更新，或使用 unsloth studio update.

Windows PowerShell：

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

使用相同的命令进行更新，或使用 unsloth studio update.

启动：

unsloth studio -H 0.0.0.0 -p 8888

有关 Unsloth Studio 的详细安装说明和要求， 查看我们的指南.

从主仓库安装

macOS、Linux、WSL 开发者安装：

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

Windows 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：

git clone https://github.com/unslothai/unsloth
cd unsloth
git checkout nightly
./install.sh --local

然后每次都这样启动：

unsloth studio -H 0.0.0.0 -p 8888

夜间版 - Windows：

在 Windows 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
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_studio

• Windows（PowerShell）： Remove-Item -Recurse -Force "$HOME\.unsloth\studio\unsloth_studio"

这会移除应用程序，但会保留你的模型检查点、导出、历史记录、缓存和聊天内容。

2. 移除快捷方式和符号链接

macOS：

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

Linux：

rm -f ~/.local/share/applications/unsloth-studio.desktop ~/Desktop/unsloth-studio.desktop

WSL / Windows（PowerShell）：

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：

rm -f ~/.local/bin/unsloth

Windows（PowerShell）： 安装程序已将虚拟环境的 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 缓存中的——以上步骤都不会删除它们。若你想回收那部分磁盘空间，请参见 删除模型文件 下面的说明。

注意：使用 rm -rf 命令将 删除所有内容，包括你的历史记录、缓存、聊天等。

删除缓存的 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 pip 安装（推荐）以获得最新的 pip 版本：

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：

pip install unsloth

若要同时安装 vLLM 和 Unsloth ，请执行：

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

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

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

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

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

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

现在已支持 Python 3.13！

卸载 Unsloth Core

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

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

高级 Pip 安装

请 不要 在以下情况下使用此方法： Conda.

由于依赖问题，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，请使用：

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

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

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

还有其他示例：

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 安装命令：

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

或者，在 Python REPL 中手动运行下面的代码：

# Licensed under the Apache License, Version 2.0 (the "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')