Unsloth Studio 安装

了解如何在本地设备上安装 Unsloth Studio。

Unsloth Studio 可在 Windows、Linux、WSL 和 MacOS 上运行。你应在每台设备上使用相同的安装流程，尽管系统要求可能因设备而异。

WindowsMacOSLinux & WSLDocker开发者安装

• Mac： 类似 CPU - 聊天 + 数据配方 目前可用。 MLX 训练即将推出。

• CPU：Unsloth 在没有 GPU 的情况下仍可运行，但仅限于聊天 + 数据配方。

• 训练： 可在 NVIDIA：RTX 30、40、50、Blackwell、DGX Spark/Station 等 + Intel GPU

• 即将推出： 支持 Apple MLX 和 AMD.

安装说明

请记住，各设备的安装说明都是相同的：

1

安装 Unsloth

MacOS、Linux、WSL：

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

Windows PowerShell：

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

由于使用了预编译的 llama.cpp 二进制文件，首次安装现在应快 6 倍，体积减少 50%。

WSL 用户： 系统会提示你输入 sudo 密码以安装构建依赖项（cmake, git, libcurl4-openssl-dev).

2

启动 Unsloth Studio

unsloth studio -H 0.0.0.0 -p 8888

然后在浏览器中打开 http://localhost:8888 。

3

入门引导

首次启动时，你需要创建一个密码来保护你的账户，并在稍后重新登录。随后你会看到一个简短的入门向导，用于选择模型、数据集和基本设置。你可以随时跳过它。

4

开始训练和运行

启动后即可立即开始微调和构建数据集。请查看我们的分步指南，开始使用 Unsloth Studio：

Get Started

更新 Unsloth Studio：

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

MacOS、Linux、WSL：

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

Windows PowerShell：

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

或者使用（目前在 Windows 上不起作用）：

unsloth studio update 

系统要求

Windows

Unsloth Studio 可直接在 Windows 上运行，无需 WSL。要训练模型，请确保你的系统满足以下要求：

要求

• Windows 10 或 Windows 11（64 位）

• 已安装驱动程序的 NVIDIA GPU

• 应用安装程序 （包含 winget): 此处

• Git: winget install --id Git.Git -e --source winget

• Python：版本 3.11 及以上，但不包括 3.14

• 在 Python 环境中工作，例如 uv, venv，或 conda/mamba

MacOS

Unsloth Studio 可在 Mac 设备上运行，用于 聊天 用于 GGUF 模型和 数据配方 (导出 （即将推出）。 MLX 训练即将推出！

• macOS 12 Monterey 或更高版本（Intel 或 Apple Silicon）

• 安装 Homebrew： 此处

• Git： brew install git

• cmake： brew install cmake

• openssl： brew install openssl

• Python：版本 3.11 及以上，但不包括 3.14

• 在 Python 环境中工作，例如 uv, venv，或 conda/mamba

Linux & WSL

• Ubuntu 20.04+ 或类似发行版（64 位）

• 已安装驱动程序的 NVIDIA GPU

• CUDA 工具包（建议 12.4+，blackwell 需 12.8+）

• Git： sudo apt install git

• Python：版本 3.11 及以上，但不包括 3.14

• 在 Python 环境中工作，例如 uv, venv，或 conda/mamba

Docker

我们的 Docker 镜像现在已可用于 Studio！我们正在开发 Mac 兼容性。

• 拉取我们最新的 Unsloth 容器镜像： docker pull unsloth/unsloth

• 通过以下命令运行容器：

docker run -d -e JUPYTER_PASSWORD="mypassword" \
  -p 8888:8888 -p 8000:8000 -p 2222:22 \
  -v $(pwd)/work:/workspace/work \
  --gpus all \
  unsloth/unsloth

更多信息， 请看这里.

• 在以下地址访问你的 studio 实例 http://localhost:8000 或外部 IP 地址 http://external_ip_address:8000/

仅限 CPU

Unsloth Studio 支持 CPU 设备用于 聊天 用于 GGUF 模型和 数据配方 (导出 （即将推出）

• 与上面 Linux 部分提到的要求相同（不包括 NVIDIA GPU 驱动）以及 MacOS。

开发者安装（高级）

macOS、Linux、WSL 开发者安装：

curl -LsSf https://astral.sh/uv/install.sh | sh
uv venv unsloth_studio --python 3.13
source unsloth_studio/bin/activate
uv pip install unsloth --torch-backend=auto
unsloth studio setup
unsloth studio -H 0.0.0.0 -p 8888

Windows PowerShell 开发者安装：

winget install -e --id Python.Python.3.13
winget install --id=astral-sh.uv  -e
uv venv unsloth_studio --python 3.13
.\unsloth_studio\Scripts\activate
uv pip install unsloth --torch-backend=auto
unsloth studio setup
unsloth studio -H 0.0.0.0 -p 8888

Nightly - MacOS、Linux、WSL：

curl -LsSf https://astral.sh/uv/install.sh | sh
git clone --filter=blob:none https://github.com/unslothai/unsloth.git unsloth_studio
cd unsloth_studio
uv venv --python 3.13
source .venv/bin/activate
uv pip install -e . --torch-backend=auto
unsloth studio setup
unsloth studio -H 0.0.0.0 -p 8888

然后每次启动时：

cd unsloth_studio
source .venv/bin/activate
unsloth studio -H 0.0.0.0 -p 8888

Nightly - Windows：

在 Windows PowerShell 中运行：

winget install -e --id Python.Python.3.13
winget install --id=astral-sh.uv  -e
git clone --filter=blob:none https://github.com/unslothai/unsloth.git unsloth_studio
cd unsloth_studio
uv venv --python 3.13
.\.venv\Scripts\activate
uv pip install -e . --torch-backend=auto
unsloth studio setup
unsloth studio -H 0.0.0.0 -p 8888

然后每次启动时：

cd unsloth_studio
.\.venv\Scripts\activate
unsloth studio -H 0.0.0.0 -p 8888

卸载

你可以通过删除其安装文件夹来卸载 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 也可以更改默认缓存根目录。

Google Colab 笔记本

我们创建了一个 免费的 Google Colab 笔记本 ，这样你就可以在 Colab 的 T4 GPU 上探索 Unsloth 的全部功能。你可以训练并运行大多数参数量不超过 22B 的模型，也可以切换到更大的 GPU 以运行更大的模型。只需点击“Run all”，安装完成后 UI 应该会弹出。

Google Colabcolab.research.google.com

安装完成后，向下滚动到 启动 Unsloth Studio 并点击 打开 Unsloth Studio ，位于左侧显示的白色框中：

继续向下滚动，即可看到实际的 UI。

我们现在会预编译 llama.cpp 二进制文件，以获得更快的安装速度。

有时 Studio 链接可能会返回错误。这是因为你可能在使用广告拦截器，或者 Mozilla 或 Google Colab 期望你停留在 Colab 页面；如果它检测到不活动，可能会关闭 GPU 会话。不过，你仍然可以稍微向下滚动

故障排除

问题	修复
Python 版本错误	sudo apt install python3.12 python3.12-venv 版本 3.11 及以上，但不包括 3.14
未找到 nvidia-smi	从 https://www.nvidia.com/Download/index.aspx 安装 NVIDIA 驱动程序
未找到 nvcc （CUDA）	sudo apt install nvidia-cuda-toolkit 或将 /usr/local/cuda/bin 添加到 PATH
llama-server 构建失败	非致命问题，Studio 仍可运行，GGUF 推理将不可用。安装 cmake 并重新运行 setup 以修复。
未找到 cmake	sudo apt install cmake
未找到 git	sudo apt install git
构建失败	删除 ~/.unsloth/llama.cpp 并重新运行 setup