Unsloth Studio 安装

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

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

WindowsmacOSLinux 与 WSLDocker

• 训练： 支持的 NVIDIA GPU：RTX 3090、Blackwell 50 系列、DGX Spark 等。

• Mac： 类似 CPU — 目前仅支持聊天功能。 MLX 训练即将推出。

• CPU：Unsloth 在没有 GPU 的情况下仍然可用，但仅用于 聊天 推理。

• 即将推出： 支持 Apple MLX, AMD，以及 Intel.

安装说明

请记住安装说明在每台设备上相同：

1

安装 Unsloth

MacOS、Linux、WSL：

对于 MacOS，请确保已安装 cmake 如果没有，请运行 brew install cmake.

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

首次安装可能需要 5-10 分钟。这是正常的，因为 llama.cpp 需要编译二进制文件。请不要取消它。 我们正在准备预编译二进制文件，这样下次就不会花那么长时间。

WSL 用户： 您将被提示输入您的 sudo 密码以安装构建依赖项（cmake, git, libcurl4-openssl-dev).

2

启动 Unsloth Studio

MacOS、Linux、WSL：

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

Windows Powershell：

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

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

3

入门引导

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

4

开始训练和运行

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

Get Started

系统要求

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 的要求相同。

Google Colab

我们已创建一个 免费的 Google Colab 笔记本 以便您可以在 Colab 的 T4 GPU 上探索 Unsloth 的所有功能。您可以训练并运行大多数最多 22B 参数的模型，并在需要更大模型时切换到更大的 GPU。只需点击“全部运行”，安装完成后界面应会弹出。

在 T4 GPU 上编译 llama.cpp 需要 30 分钟以上，因此我们建议使用更大的 GPU 以获得更快的速度。

Google Colabcolab.research.google.com

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

有时 Studio 链接可能返回错误。发生这种情况是因为 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 并重新运行设置以修复。
找不到 cmake	sudo apt install cmake
找不到 git	sudo apt install git
构建失败	删除 ~/.unsloth/llama.cpp 并重新运行设置