通过 pip 和 uv 安装 Unsloth

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

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

Unsloth Studio

MacOS、Linux、WSL：

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

使用相同的命令进行更新。

Windows PowerShell：

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

使用相同的命令进行更新。

启动 Unsloth Studio：

unsloth studio -H 0.0.0.0 -p 8888

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

卸载 Unsloth Studio

你可以通过删除其安装文件夹来卸载 Unsloth Studio，通常位于 $HOME/.unsloth/studio 在 Mac/Linux/WSL 上，以及 %USERPROFILE%\.unsloth\studio 在 Windows 上。或者运行：

• MacOS、WSL、Linux： rm -rf ~/.unsloth/studio

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

• 可选： 删除 $HOME\.unsloth 在 Windows 上，或 ~/.unsloth 在 MacOS/Linux/WSL 上，如果你想删除所有 Unsloth 文件

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

删除模型文件

你可以通过模型搜索中的垃圾桶图标删除旧模型文件，或者从默认的 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 时遇到依赖问题，许多用户通过强制卸载并重新安装 Unsloth 解决了问题：

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

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 要稍微复杂一些。对于 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，请使用：

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')