> For the complete documentation index, see [llms.txt](https://unsloth.ai/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://unsloth.ai/docs/zh/kuai-su-kai-shi/install/docker.md).
# 通过 Docker 安装 Unsloth
使用我们的官方 Docker 容器安装 Unsloth
了解如何使用 Unsloth Docker 容器运行和训练模型。无需设置 - 所有依赖项都已预先安装。只需拉取镜像，即可在本地 NVIDIA 或 AMD GPU 上开始运行和训练模型。
| **NVIDIA** Docker： [**`unsloth/unsloth`**](https://hub.docker.com/r/unsloth/unsloth) | **AMD** Docker： [**`unsloth/unsloth-rocm`**](https://hub.docker.com/r/unsloth/unsloth-rocm) |
| ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------- |
{% hint style="success" %}
**NEW 2026年9月：Unsloth Docker 容器现已更新，包含 Unsloth Studio 和 AMD 支持。**
Unsloth 与笔记本和脚本共享相同的缓存，以避免不必要的重复下载。
{% endhint %}
### 快速入门
本指南部分适用于配备 NVIDIA GPU 的系统。如果你有 [AMD 请看这里](#amd-quickstart).
{% tabs %}
{% tab title="Linux / WSL" %}
要在 NVIDIA GPU 上获取 Unsloth 的 Docker，请在终端中运行以下命令：
```bash
docker run -d --name unsloth --gpus all --ipc=host \
--ulimit memlock=-1 --ulimit stack=67108864 \
-p 8000:8000 -p 8888:8888 \
-e JUPYTER_PASSWORD="mypassword" \
-v "$PWD":/workspace/host \
-v "$HOME/.cache/huggingface":/workspace/.cache/huggingface \
-v unsloth-studio:/opt/unsloth-studio \
unsloth/unsloth
```
* 请从你的项目文件夹中运行，因为该文件夹（`$PWD`）会变成 `/workspace/host`.
* 这些标志的作用：暴露 8000 端口（Unsloth Studio）和 8888 端口（JupyterLab）；这三个 `-v` 标志会保留你的文件、模型和 Unsloth Studio 数据。
* 要求：NVIDIA 驱动 570.26 或更新版本。
{% endtab %}
{% tab title="Windows（PowerShell）" %}
在 Powershell 中运行以下命令：
```powershell
docker run -d --name unsloth --gpus all --ipc=host `
--ulimit memlock=-1 --ulimit stack=67108864 `
-p 8000:8000 -p 8888:8888 `
-e JUPYTER_PASSWORD="mypassword" `
-v "${PWD}:/workspace/host" `
-v "${HOME}/.cache/huggingface:/workspace/.cache/huggingface" `
-v "unsloth-studio:/opt/unsloth-studio" `
unsloth/unsloth
```
* 请从你的项目文件夹中运行，因为该文件夹（`${PWD}`）会变成 `/workspace/host`.
* 这些标志的作用：暴露 8000 端口（Unsloth Studio）和 8888 端口（JupyterLab）；这三个 `-v` 标志会保留你的文件、模型和 Unsloth Studio 数据。
* 要求：NVIDIA 驱动 570.26 或更新版本。
{% endtab %}
{% endtabs %}
### 前置条件
如果你还没有为 NVIDIA Container Toolkit 安装 Docker，请按以下步骤操作：
{% tabs %}
{% tab title="Linux / WSL" %}
安装 [Docker Engine](https://docs.docker.com/engine/install/) 或 [Docker Desktop](https://docs.docker.com/desktop/)，如果你还没有：
```bash
curl -fsSL https://get.docker.com -o get-docker.sh && sh get-docker.sh
```
如果你有 NVIDIA GPU，请安装 [NVIDIA Container Toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html#installation) 如果你还没有：
```bash
curl -fsSL https://raw.githubusercontent.com/unslothai/unsloth/main/docker/install_nvidia_toolkit.sh -o install_nvidia_toolkit.sh && sudo -E bash install_nvidia_toolkit.sh
```
{% endtab %}
{% tab title="Windows" %}
**安装 Docker Desktop 和 NVIDIA 驱动程序。**
安装 [Windows 版 Docker Desktop](https://docs.docker.com/desktop/setup/install/windows-install/) 以及最新的 [NVIDIA Windows 驱动程序](https://www.nvidia.com/Download/index.aspx)。 \
然后在 PowerShell 中更新 WSL：
```powershell
wsl --update
```
在 Docker Desktop 设置中，选择 **通用** 并确认 **使用基于 WSL 2 的引擎** 已启用。继续之前请等待引擎启动。
无需单独安装 NVIDIA Container Toolkit。 [Windows GPU 故障排除](https://docs.docker.com/desktop/features/gpu/).
{% endtab %}
{% endtabs %}
### AMD 快速开始
本指南部分适用于配备 AMD GPU 的系统。如果你有 [NVIDIA 请看这里](#quickstart).
{% tabs %}
{% tab title="Linux" %}
要在 AMD GPU 上获取 Unsloth 的 Docker，请在终端中运行以下命令：
```bash
GPU_FLAGS="--device /dev/kfd"
[ -e /dev/dri ] && GPU_FLAGS="$GPU_FLAGS --device /dev/dri"
for g in video render; do
gid=$(getent group "$g" | cut -d: -f3)
[ -n "$gid" ] && GPU_FLAGS="$GPU_FLAGS --group-add $gid"
done
docker run -d --name unsloth \
$GPU_FLAGS \
--ipc=host \
--ulimit memlock=-1 --ulimit stack=67108864 \
-p 8000:8000 -p 8888:8888 \
-e JUPYTER_PASSWORD="mypassword" \
-v "$PWD":/workspace/host \
-v "$HOME/.cache/huggingface":/workspace/.cache/huggingface \
-v unsloth-studio:/opt/unsloth-studio \
unsloth/unsloth-rocm
```
* 请从你的项目文件夹中运行，因为该文件夹（`$PWD`）会变成 `/workspace/host`.
* 这些标志的作用： `$GPU_FLAGS` 传递 GPU 设备节点和组 ID；端口 8000（Unsloth Studio）和 8888（JupyterLab）；这三个 `-v` 标志会保留你的文件、模型和 Unsloth Studio 数据。
* 要求：一个可正常工作的 `amdgpu` 驱动程序。基于 ROCm 7.2 构建，支持 RDNA1 及更新版本，以及 CDNA。
{% endtab %}
{% tab title="WSL" %}
在 WSL 中，AMD GPU 通过 WSL2 的 DXG 桥接访问。请在你的 WSL2 发行版中运行此命令，而不是在 PowerShell 中运行，WSL2 没有 `/dev/kfd` 因此 GPU 会改为以 `/dev/dxg` 的形式传递：
```bash
docker run -d --name unsloth --device /dev/dxg --ipc=host \
--ulimit memlock=-1 --ulimit stack=67108864 \
-e HSA_ENABLE_DXG_DETECTION=1 \
-e LD_LIBRARY_PATH=/usr/lib/wsl/lib:/opt/rocm/lib \
-p 8000:8000 -p 8888:8888 \
-e JUPYTER_PASSWORD="mypassword" \
-v /usr/lib/wsl/lib:/usr/lib/wsl/lib:ro \
-v "$PWD":/workspace/host \
-v "$HOME/.cache/huggingface":/workspace/.cache/huggingface \
-v unsloth-studio:/opt/unsloth-studio \
unsloth/unsloth-rocm
```
* 请在 WSL2（`wsl -d Ubuntu`）内部运行，并从你的项目文件夹中运行，因为该文件夹（`$PWD`）会变成 `/workspace/host`.
* 这些标志的作用： `--device /dev/dxg` 以及 `/usr/lib/wsl/lib` 挂载可通过 WSL2 传递 GPU；端口 8000（Unsloth Studio）和 8888（JupyterLab）；这三个 `-v` 标志会保留你的文件、模型和 Unsloth Studio 数据。
* 要求：主机上安装了支持 WSL2 的 AMD Windows 驱动程序
{% endtab %}
{% tab title="Windows（PowerShell）" %}
在 PowerShell 中运行以下命令：
```powershell
docker run -d --name unsloth --device /dev/dxg --ipc=host `
--ulimit memlock=-1 --ulimit stack=67108864 `
-e HSA_ENABLE_DXG_DETECTION=1 `
-e LD_LIBRARY_PATH=/usr/lib/wsl/lib:/opt/rocm/lib `
-p 8000:8000 -p 8888:8888 `
-e JUPYTER_PASSWORD="mypassword" `
-v "/usr/lib/wsl/lib:/usr/lib/wsl/lib:ro" `
-v "${PWD}:/workspace/host" `
-v "${HOME}/.cache/huggingface:/workspace/.cache/huggingface" `
-v "unsloth-studio:/opt/unsloth-studio" `
unsloth/unsloth-rocm
```
* 请从你的项目文件夹中运行，因为该文件夹（`${PWD}`）会变成 `/workspace/host`.
* 要求：主机上安装支持 WSL2 的 AMD Windows 驱动程序，并且 Docker Desktop 使用 WSL 2 引擎。
{% endtab %}
{% endtabs %}
如果你还没有安装 Docker，请运行以下命令：
```bash
curl -fsSL https://get.docker.com -o get-docker.sh && sh get-docker.sh
```
AMD 不需要容器工具包，只需要主机上的 `amdgpu` 驱动程序。在 Windows 上，安装 Docker Desktop 和支持 WSL2 的 AMD 驱动程序。
### 📖 使用指南
#### Unsloth Studio 设置
Unsloth Studio 已预安装，因此你可以在同一个 Docker 容器中与模型聊天、微调它们并生成图像。
{% stepper %}
{% step %}
**启动 Unsloth 容器。** \
运行完整的 `docker run` 命令，适用于你的操作系统，在 **快速入门** 中，并等待大约一分钟让它启动。如果容器已经在运行，则跳过此步骤。
```bash
docker start unsloth
```
{% endstep %}
{% step %}
**查找你的密码。** \
如果你还不知道密码，请检查容器日志：
```bash
docker logs -f unsloth
```
查找 **Unsloth container ready** 以获取链接和密码详情。按 **Ctrl+C** 停止跟踪日志；容器会继续运行。
{% endstep %}
{% step %}
**登录**
打开 [`http://localhost:8000`](http://localhost:8000) 并以 `unsloth`身份登录。首次设置时，请使用生成的密码，并在提示时选择一个新密码。否则，使用你现有的密码。
{% endstep %}
{% step %}
**忘记密码了？**
```bash
docker exec unsloth unsloth studio reset-password --username unsloth
```
这会生成新密码，注销现有会话并撤销 API 密钥。无需重启。这些命令假设你的容器名为 `unsloth`。如有需要，运行 `docker ps` 来查找它的名称或 ID。
{% hint style="info" %}
如果 Docker 运行在另一台机器上（例如云 GPU 或服务器）， `localhost` 指的是你自己的电脑。你必须在打开链接之前转发端口。运行 `ssh -L 8000:localhost:8000 -L 8888:localhost:8888 user@your-server`。参见 [安全说明](#security-notes) 部分了解详情。
{% endhint %}
{% endstep %}
{% endstepper %}
#### **与模型聊天**
{% hint style="info" %}
Unsloth Studio 和 JupyterLab 共享同一个 GPU。加载到 Unsloth 中的模型会一直占用 GPU 内存，直到你卸载它。如果内存不足，请在 Unsloth 中卸载模型或停止 notebook 内核。
{% endhint %}
{% stepper %}
{% step %}
**选择并下载模型**
打开 **选择模型** 在页面顶部。浏览 **推荐**，或输入模型名称并点击 **搜索 Hub** 以搜索 Hugging Face。你也可以在 **模型 Hub**.
中浏览模型。对于 GGUF 模型，请选择适合你可用 RAM 和 VRAM 的量化方式。避免选择标记为 **OOM**.
在发送第一条消息之前，等待模型完成下载和加载。你还可以从 **On Device**.
浏览推荐模型或按名称搜索。
{% hint style="info" %}
已下载的模型存储在 `/workspace/.cache/huggingface`中。借助快速开始的卷挂载，该缓存会与 notebooks 共享，并且即使你移除容器，它也会保留在你的电脑上。
{% endhint %}
{% endstep %}
{% step %}
**发送消息**
模型准备好后，输入消息并按 **Enter**。试试：
> 解释 Docker 容器和虚拟机的区别。
请参见 [Unsloth Studio Chat](/docs/zh/xin/studio/chat.md) 用于网页搜索和更多聊天设置的指南。
{% endstep %}
{% endstepper %}
#### **训练模型**
你可以训练跨文本的模型， [视觉](https://unsloth.ai/docs/basics/vision-fine-tuning) 和 [音频](https://unsloth.ai/docs/basics/text-to-speech-tts-fine-tuning)，并且也支持 [嵌入](https://unsloth.ai/docs/basics/embedding-finetuning) 以及图像扩散。全部都来自同一个 Docker 镜像。
**选择模型和数据集**
选择 **训练** 并打开 **配置**。选择一个模型和训练方法，然后选择一个 Hugging Face 数据集或上传你自己的数据集。
**开始训练**
审查 **参数** 在 **简单** 或 **高级** 模式，然后点击 **开始训练**。在 **当前运行**.
**试用你训练好的模型**
训练完成后，点击 **在聊天中比较**。使用相同提示测试原始模型和微调后的模型，看看它们的回答有何不同。
请参见 [Studio 训练指南](https://unsloth.ai/docs/new/studio/start) 了解更多细节，或使用 [数据配方](https://unsloth.ai/docs/new/studio/data-recipe) 来准备你的数据集。
#### **生成图像**
{% stepper %}
{% step %}
**打开 Images 并选择一个模型**
选择 **图像** 在侧边栏中。 **创建** 工作流默认会打开。
.png?alt=media&token=ff61651a-4560-4473-9232-d06024cb216e)
打开 Images 以根据文本提示创建图像。
打开 **选择图像模型** 并从中选择 **推荐**，例如 Z-Image-Turbo。对于 GGUF 模型，请选择适合你设备的量化方式。 **过紧** 可能运行较慢； **OOM** 的模型不太可能适配。
.png?alt=media&token=6f1b3e41-2c5a-4c5a-9c75-f624c6f4ede6)
选择一个图像模型和适合你设备的量化方式。
{% endstep %}
{% step %}
**输入提示并生成**
描述你想创建的图像。例如：
> 日本庭院中一个锦鲤池的俯视图，数十条橙色、白色和黑色锦鲤紧密成群游动，池水清澈到可以看到石质池底，水面漂浮着红色枫叶。明亮的正午光线，色彩饱和，清晰的反射。写实照片，50mm。
保持图像设置为默认值并点击 **生成**.
.png?alt=media&token=47888a19-5384-4ace-b5d7-f90cf4fb9b0f)
使用 Z-Image-Turbo 的生成示例。
在图库中打开你的图像并点击 **下载** 以保存它，或 **配方** 以复用其提示和设置。
**变换**, **局部重绘** 和 **编辑** 取决于加载的模型。请参见 [图像扩散指南](https://unsloth.ai/docs/basics/diffusion-image) 以了解支持的工作流和设置。
{% endstep %}
{% endstepper %}
#### **访问 JupyterLab**
{% columns %}
{% column %}
Unsloth Docker 镜像包含 JupyterLab 和可直接使用的 notebooks。
打开 [`http://localhost:8888`](http://localhost:8888) 并登录。使用你在启动容器时选择的 `JUPYTER_PASSWORD` 。如果你没有设置，请使用容器日志中打印的生成密码。
{% hint style="info" %}
JupyterLab 密码在容器创建时设置。要更改它，请删除并使用新密码重新创建容器。
{% endhint %}
{% endcolumn %}
{% column %}
{% endcolumn %}
{% endcolumns %}
登录后，你会看到 **Unsloth Notebooks**，其中文件夹按模型和任务分组。
这些文件夹包含 `/workspace/unsloth-notebooks`中 notebook 文件的快捷方式。每次容器启动时，notebooks 都会从 GitHub 刷新，而不会覆盖
\
你的编辑。
双击 **01 Main Notebooks** 浏览示例，或选择一个类别，例如视觉、语音或强化学习。
