> 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" %}
**新功能 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 或更新版本。

<figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2Fz1bQUO7kRRL6jrzDKsRO%2FiShot_2026-09-17_16.30.18.png?alt=media&amp;token=1a5a23ee-e384-4bc7-b5f5-4cb934989094" alt=""><figcaption></figcaption></figure>
{% 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 或更新版本。

<figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2F70dKPYWYN9PrkPkMtbdg%2Fimage.png?alt=media&amp;token=5b4a4309-c97b-4e65-8daa-babb312a97ca" alt=""><figcaption></figcaption></figure>
{% 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)。\n然后在 PowerShell 中更新 WSL：

```powershell
wsl --update
```

在 Docker Desktop 设置中，选择 **常规** 并确认 **使用基于 WSL 2 的引擎** 已启用。继续之前请等待引擎启动。

<figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FNSQSDRFKVGyePWp7zKZA%2Fimage.png?alt=media&amp;token=0516785a-3fc1-41bc-8690-b98df7085fbf" alt=""><figcaption></figcaption></figure>

无需单独安装 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` 挂载会将 GPU 通过 WSL2 传递；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 驱动，以及使用 WSL 2 引擎的 Docker Desktop。
  {% 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 容器已就绪** 以及链接和密码详情。按 **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。你也可以在 **模型仓库**.

中浏览模型。对于 GGUF 模型，选择与可用 RAM 和 VRAM 相匹配的量化方式。避免标记为 **OOM**.

在发送第一条消息之前，请等待模型完成下载和加载。你也可以从 **设备上**.

<figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FgyDczCQqKkgh7ap2PuNU%2Fimage.png?alt=media&amp;token=740ee435-e68f-4811-8bb6-aa093526f74f" alt="Unsloth Studio model selector with Hugging Face search and recommended GGUF models." width="375"><figcaption><p>中再次选择已下载的模型。</p></figcaption></figure>

{% hint style="info" %}
已下载的模型存储在 `/workspace/.cache/huggingface`。通过快速入门的卷挂载，这个缓存会与 notebooks 共享，即使你删除容器，它也会保留在你的电脑上。
{% endhint %}
{% endstep %}

{% step %}
**发送消息**

模型准备好后，输入一条消息并按 **Enter**。试试：

> 解释 Docker 容器与虚拟机有何不同。

<figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FKfzGAT0DLWirgWvkfK1x%2Fimage.png?alt=media&amp;token=afff9dd2-06d4-4f7b-bba5-8a4835143090" alt=""><figcaption></figcaption></figure>

查看 [Unsloth Studio 聊天](/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 镜像。

<figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2F66Vvgt0l5iqAkAksIRYF%2Fimage.png?alt=media&amp;token=8fcb1ad6-2b53-4128-87fa-a47bcd1deab4" alt="" width="563"><figcaption></figcaption></figure>

**选择模型和数据集**

选择 **训练** 并打开 **配置**。选择一个模型和训练方法，然后选择 Hugging Face 数据集或上传你自己的数据集。

**开始训练**

查看 **参数** 在 **简单** 或 **高级** 模式下，然后点击 **开始训练**。在 **当前运行**.

<figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FD7qpbGJLY5YMv0E0QgrB%2Ftrainingrun_LLM-unsloth.gif?alt=media&amp;token=feb766a7-1a7b-4f47-b5f4-b38e3a0d1470" alt=""><figcaption></figcaption></figure>

**中跟踪进度、损失和 GPU 使用情况**

训练完成后，点击 **在聊天中比较**。使用相同的提示测试原始模型和微调后的模型，看看它们的回复有何不同。

查看 [Studio 训练指南](https://unsloth.ai/docs/new/studio/start) 了解更多细节，或使用 [数据食谱](https://unsloth.ai/docs/new/studio/data-recipe) 来准备你的数据集。

#### **生成图像**

{% stepper %}
{% step %}
**打开 Images 并选择一个模型**

选择 **图像** 在侧边栏中。 **创建** 工作流默认打开。

<figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2F6WVNnM49nQoTBfv57RAs%2Fimage%20(529).png?alt=media&amp;token=ff61651a-4560-4473-9232-d06024cb216e" alt="Unsloth Studio Images page with Create selected in the sidebar and prompt controls." width="375"><figcaption><p>打开 Images，通过文本提示创建图像。</p></figcaption></figure>

打开 **选择图像模型** 并从 **推荐**中选择，例如 Z-Image-Turbo。对于 GGUF 模型，请选择适合你设备的量化方式。 **TIGHT** 可能运行缓慢； **OOM** 很可能装不下。

<figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2F1gPBEymJifbpIE9lGfvd%2Fimage%20(530).png?alt=media&amp;token=6f1b3e41-2c5a-4c5a-9c75-f624c6f4ede6" alt="Image model selector showing Z-Image-Turbo-GGUF and available quantizations." width="375"><figcaption><p>选择一个图像模型和适合你设备的量化方式。</p></figcaption></figure>
{% endstep %}

{% step %}
**输入提示并生成**

描述你想创建的图像。例如：

> 日本庭院中锦鲤池的俯拍，数十条橙色、白色和黑色锦鲤紧密成群游动，清澈的池水能看见石质池底，红色枫叶漂浮在水面上。明亮的正午光线，饱和色彩，清晰倒影。写实照片，50mm。

保持图像设置为默认值，然后点击 **生成**.

<figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2Fy0qucNcG7XQlDVvv3XZE%2Fimage%20(493).png?alt=media&amp;token=47888a19-5384-4ace-b5d7-f90cf4fb9b0f" alt="Unsloth Studio Create images page with Z-Image-Turbo loaded, a koi pond prompt, a generated image, and Recipe and Download controls." width="563"><figcaption><p>使用 Z-Image-Turbo 的示例生成结果。</p></figcaption></figure>

在图库中打开你的图像并点击 **下载** 以保存它，或者点击 **配方** 以复用其提示词和设置。

**转换**, **局部重绘** 和 **编辑** 取决于所加载的模型。请参阅 [图像扩散指南](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 %}

<figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FQapcJDBCYgxaEfG5zEEn%2Fimage.png?alt=media&amp;token=8eb72fbd-8ca1-43f6-9c6a-e45cb7a06da0" alt="" width="375"><figcaption></figcaption></figure>
{% endcolumn %}
{% endcolumns %}

登录后，你会看到 **Unsloth Notebooks**，其中的文件夹按模型和任务分组。

这些文件夹包含指向以下位置的 notebook 文件的快捷方式： `/workspace/unsloth-notebooks`。每次容器启动时，notebooks 都会从 GitHub 刷新，不会覆盖\r\n你的编辑内容。

双击 **01 Main Notebooks** 来浏览示例，或者选择某个类别，例如视觉、语音或强化学习。

<div data-with-frame="true"><figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FXceIgyo451mqw1hchpXR%2Fimage.png?alt=media&amp;token=b32a2968-0e94-4eff-b6a5-ed9f9b617ca4" alt="" width="563"><figcaption></figcaption></figure></div>

#### **在 notebook 中微调模型**

在开始训练之前，请卸载在 Unsloth Studio 中加载的任何模型，以便 notebook 拥有所需的 GPU 内存。

在 **01 Main Notebooks** 中打开一个 notebook，并按照其说明操作。按 **Shift+Enter** 按顺序运行每个单元格。首次运行会将模型下载到 Hugging Face 缓存中。

例如， `Gemma3_(4B)-Vision.ipynb` 会引导你完成将方程图片转换为 LaTeX 的 Gemma 3 4B 微调过程。

<div data-with-frame="true"><figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FyLdWCorjvMlW0OPkE2v4%2Fimage.png?alt=media&amp;token=ca2e62b5-5857-4cbf-89f4-735030f1123b" alt="" width="563"><figcaption></figcaption></figure></div>

训练完成后，使用 notebook 的 **推理** 部分测试你的模型。它会在一张方程图片上测试训练后的模型。下面给出了该方程，这里以更高分辨率重新绘制以便阅读。

<div data-with-frame="true"><figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FGJdMUUr0ig4NQL5TMk2I%2Fimage.png?alt=media&amp;token=fa1eb118-dcbd-4ad3-a8f4-48e47659c143" alt="" width="563"><figcaption></figcaption></figure></div>

模型从原始数据集图片生成 LaTeX。它会在单元格下方打印 LaTeX 结果。

#### **保存并导出你的模型**

按照 notebook 的保存部分保存你训练好的 LoRA 适配器，或导出你合并后的模型。

像 `"gemma_3_lora"` 这样的相对路径会保存在 notebook 旁边的 `/workspace/Unsloth Notebooks/...`中。该文件夹位于容器内，因此在删除容器时会被删除。要将结果保留在你的电脑上，请保存到 `/workspace/host`.

* **在本地保存 LoRA 适配器：** 此单元格默认运行。将路径改为 `/workspace/host`.

  ```python
  model.save_pretrained("/workspace/host/gemma_3_lora")
  processor.save_pretrained("/workspace/host/gemma_3_lora")
  ```
* **导出合并后的 16 位模型：** 在导出单元格中，将 `if False:` 改为 `if True:` 以选择你想要的选项。只需选择一个。

  ```python
  if True: model.save_pretrained_merged("/workspace/host/unsloth_finetune", processor)
  ```

<div data-with-frame="true"><figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FERw6laeLKXj5mLtoWB8y%2Fimage.png?alt=media&amp;token=5d43449b-cc98-4448-93f5-79599d39148f" alt="" width="563"><figcaption></figcaption></figure></div>

* **上传到 Hugging Face：** 你需要一个具有写入权限的 token 才能上传。将 `YOUR_USERNAME` 和 `YOUR_HF_TOKEN` 占位符替换为你自己的信息。

更多指导请参阅我们的 [微调指南](https://unsloth.ai/docs/get-started/fine-tuning-llms-guide), [RL 指南](https://unsloth.ai/docs/get-started/reinforcement-learning-rl-guide)，以及 [notebook 集合](https://github.com/unslothai/notebooks).

#### 停止、重启并更新容器

命令使用的是容器名称或 ID，而不是镜像名称 `unsloth/unsloth`.

关闭容器但保留它：

```bash
docker stop unsloth
```

以相同状态将其恢复：

```bash
docker start unsloth
```

再次查找你的容器，无论它是否在运行：

```bash
docker ps -a
```

停止并删除容器：

```bash
docker rm -f unsloth
```

删除容器不会删除你的模型、主机文件（`/workspace/host`）、或 Unsloth Studio 数据（账户、聊天记录和导出）。使用相同 `-v` 标志的新容器会从你上次离开的地方继续，你的 Unsloth 密码保持不变。写入容器中的其他任何内容都会丢失。

要永久删除 Unsloth Studio 的数据，请移除其卷：

```bash
docker volume rm unsloth-studio
```

要更新到最新的 Unsloth 版本，请拉取新镜像：

```bash
#NVIDIA GPU
docker pull unsloth/unsloth
#AMD GPU
docker pull unsloth/unsloth-rocm
```

然后删除旧容器，并使用相同标志再次运行快速开始命令。你的模型、文件和 Unsloth Studio 数据都会保留。

```bash
docker rm -f unsloth
```

#### **通过 SSH 连接**

除非你设置 `SSH_KEY` 或 `PUBLIC_KEY`。你将以 `root` 用户身份通过仅密钥认证在容器内的 22 端口连接。

生成 SSH 密钥：

```bash
ssh-keygen -t ed25519 -f ~/.ssh/container_key
```

SSH 密钥会在创建容器时应用，因此你必须重新创建容器才能添加它。请使用此完整命令将 SSH 端口映射到你主机上的 2222，设置密码并挂载卷。

{% tabs %}
{% tab title="NVIDIA" %}

```bash
docker run -d --name unsloth --gpus all --ipc=host \
  --ulimit memlock=-1 --ulimit stack=67108864 \
  -p 8000:8000 -p 8888:8888 -p 2222:22 \
  -e JUPYTER_PASSWORD="choose-a-jupyter-password" \
  -e UNSLOTH_STUDIO_PASSWORD="choose-a-studio-password" \
  -e SSH_KEY="$(cat ~/.ssh/container_key.pub)" \
  -v "$PWD":/workspace/host \
  -v "$HOME/.cache/huggingface":/workspace/.cache/huggingface \
  -v unsloth-studio:/opt/unsloth-studio \
  unsloth/unsloth
```

{% endtab %}

{% tab title="AMD" %}

```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 -p 2222:22 \
  -e JUPYTER_PASSWORD="choose-a-jupyter-password" \
  -e UNSLOTH_STUDIO_PASSWORD="choose-a-studio-password" \
  -e SSH_KEY="$(cat ~/.ssh/container_key.pub)" \
  -v "$PWD":/workspace/host \
  -v "$HOME/.cache/huggingface":/workspace/.cache/huggingface \
  -v unsloth-studio:/opt/unsloth-studio \
  unsloth/unsloth-rocm
```

{% endtab %}
{% endtabs %}

`UNSLOTH_STUDIO_PASSWORD` 仅在第一次 `unsloth-studio` 卷被使用时生效。请参见 [高级设置](#advanced-settings) 下方的所有环境变量、卷和端口。

连接到容器：

```bash
ssh -i ~/.ssh/container_key -p 2222 root@localhost
```

#### 📂 容器结构

* `/workspace/host/` — 你的挂载工作目录
* `/workspace/.cache/huggingface` — 模型和数据集下载
* `/workspace/.cache/triton` — 已编译的 Triton 内核
* `/workspace/unsloth-notebooks/` — 示例微调笔记本，包括你的修改
* `/workspace/Unsloth Notebooks` — 按主题分组的示例微调笔记本，每次启动时都会重建
* `/opt/unsloth-studio` — Unsloth Studio 的账户、聊天记录、输出、导出和运行记录

### 故障排除

#### **Unsloth 未检测到或未使用我的 GPU**

如果模型在 Docker 中没有使用你的 GPU，请尝试：

手动拉取最新镜像：

```bash
 #NVIDIA GPU
 docker pull unsloth/unsloth:latest
 #AMD GPU
 docker pull unsloth/unsloth-rocm:latest
```

* 以 GPU 访问权限启动容器：
  * `docker run`: `--gpus all`
  * Docker Compose： `capabilities: [gpu]`
  * AMD： `--device /dev/kfd --device /dev/dri` 再加上 `--group-add` ids（Quickstart 中的 `$GPU_FLAGS` 块）
* 在 Linux（NVIDIA）上，请确保已安装 NVIDIA Container Toolkit，并在安装后重新启动 docker。
* 在 Windows（NVIDIA）上：
  * 运行 `docker exec unsloth nvidia-smi`。如果其中列出了你的 GPU，则容器可以看到它。
  * 按照 [Docker 指南](< https://docs.docker.com/desktop/features/gpu/>)
* 在 AMD 上：运行 `docker exec unsloth rocm-smi`。如果其中列出了你的 GPU，则容器可以看到它。在 `/dev/kfd` 上出现权限错误表示 `--group-add` ids 缺失。

#### 端口已被占用

更改主机端端口，例如 `-p 8001:8000`，然后打开 [http://localhost:8001](http://localhost:8001/).

#### Unsloth Studio 在一小时后停止响应

如果自动生成的密码未更改，Unsloth Studio 会自动关闭。运行 `docker restart unsloth` 以重新启动它并更改密码。

#### 你项目文件夹中的文件归 root 所有

容器以 root 身份运行，因此请使用 `sudo chown`，或者 `core` 使用 `--user`.

### ⚙️ 高级设置

#### 环境变量

将这些中的任意一个传递给 `docker run` 使用 `-e NAME=value` 或 `--env-file`。这些适用于两者： `unsloth/unsloth` 和 `unsloth/unsloth-rocm`.

| 变量                                 | 描述                                          | 默认值                         |
| ---------------------------------- | ------------------------------------------- | --------------------------- |
| `UNSLOTH_STUDIO_PASSWORD`          | 用户的初始 Unsloth Studio 密码 `unsloth`           | 未设置：会生成一次并打印在 `docker logs` |
| `JUPYTER_PASSWORD`                 | JupyterLab 密码                               | 未设置：会生成一次并打印在 `docker logs` |
| `JUPYTER_PORT`                     | 容器内的 JupyterLab 端口                          | `8888`                      |
| `UNSLOTH_STUDIO_PORT`              | 容器内的 Unsloth Studio 端口                      | `8000`                      |
| `UNSLOTH_STUDIO_BOOTSTRAP_TIMEOUT` | 如果生成的密码未更改，Unsloth Studio 在多少秒后关闭           | `3600`                      |
| `SSH_KEY` 或 `PUBLIC_KEY`           | SSH 公钥用于 `root` 登录                          | 未设置：SSH 关闭                  |
| `UNSLOTH_ALLOW_CPU`                | 允许容器在没有 GPU 的情况下启动                          | `1`，当检测到 GPU 时取消设置          |
| `UNSLOTH_STUDIO_SECURE`            | 仅通过公开的 Cloudflare HTTPS 链接提供 Unsloth Studio | `0`                         |
| `UNSLOTH_STUDIO_CLOUDFLARE`        | 通过公开的 Cloudflare 链接共享 Unsloth Studio        | `0`                         |
| `UNSLOTH_JUPYTER_CLOUDFLARE`       | 通过公开的 Cloudflare 链接共享 JupyterLab            | `0`                         |
| `UNSLOTH_SKIP_NOTEBOOK_REFRESH`    | 跳过从 GitHub 更新示例笔记本                          | `0`                         |
| `UNSLOTH_SKIP_NOTEBOOK_SYNC`       | 跳过设置示例笔记本                                   | `0`                         |
| `HF_TOKEN`                         | Hugging Face 访问令牌                           | 未设置                         |
| `WANDB_API_KEY`                    | Weights & Biases API 密钥                     | 未设置                         |

#### 卷

{% hint style="warning" %}
**重要**：使用卷挂载以在容器运行之间保留你的工作。
{% endhint %}

不在卷中的任何内容在删除容器时都会丢失。使用以下方式挂载这些内容： `-v <host path or volume name>:<container path>`.

| 容器路径                            | 描述                                    | 建议挂载                                                 |
| ------------------------------- | ------------------------------------- | ---------------------------------------------------- |
| `/workspace/host`               | 你的项目文件                                | 你的项目文件夹，例如 `"$PWD"`                                  |
| `/workspace/.cache/huggingface` | 下载的模型和数据集                             | 你的主机 Hugging Face 缓存，例如 `"$HOME/.cache/huggingface"` |
| `/opt/unsloth-studio`           | Unsloth Studio 的账户、聊天记录、已训练模型、导出和运行记录 | 命名卷 `unsloth-studio`                                 |
| `/workspace/unsloth-notebooks`  | 示例笔记本，包括你的修改                          | 可选                                                   |
| `/workspace/.cache/triton`      | 已编译的 GPU 内核                           | 可选，可加快重启速度                                           |

* `/workspace` 是工作目录，也是 JupyterLab 打开的文件夹。
* 为 `/opt/unsloth-studio`使用命名卷，而不是主机文件夹。Unsloth Studio 需要在那里使用符号链接，而 Windows 或 macOS 的主机文件夹可能不允许，这会导致容器在启动时停止。
* 要让 Unsloth Studio 或 JupyterLab 访问更多你的文件，请在 `/workspace`下挂载更多文件夹，例如 `-v /data/datasets:/workspace/datasets`，并通过该容器路径引用它们。

#### 端口

| 端口     | 服务                     |
| ------ | ---------------------- |
| `8000` | Unsloth Studio         |
| `8888` | JupyterLab             |
| `22`   | SSH（仅当 `SSH_KEY` 已设置时） |

使用以下方式将容器端口映射到任意空闲主机端口： `-p <host>:<container>`。例如，要在主机端口上启用 SSH `2222`:

{% tabs %}
{% tab title="NVIDIA" %}

```bash
docker run -d --name unsloth --gpus all \\
  -p 8000:8000 -p 8888:8888 -p 2222:22 \
  -e SSH_KEY="$(cat ~/.ssh/id_ed25519.pub)" \\
  -v "$PWD":/workspace/host \
  -v "$HOME/.cache/huggingface":/workspace/.cache/huggingface \
  -v unsloth-studio:/opt/unsloth-studio \
  unsloth/unsloth
```

{% endtab %}

{% tab title="AMD" %}

```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 \\
  -p 8000:8000 -p 8888:8888 -p 2222:22 \
  -e SSH_KEY="$(cat ~/.ssh/id_ed25519.pub)" \\
  -v "$PWD":/workspace/host \
  -v "$HOME/.cache/huggingface":/workspace/.cache/huggingface \
  -v unsloth-studio:/opt/unsloth-studio \
  unsloth/unsloth-rocm
```

{% endtab %}
{% endtabs %}

### **🔒 安全说明**

* 容器以 root 身份运行。请使用 `unsloth/unsloth:core` 使用 `--user <uid>:<gid>` 如果你需要挂载文件归你的主机用户所有。
* SSH 关闭，除非 `SSH_KEY` 或 `PUBLIC_KEY` 已设置。它仅支持密钥认证，以 root 身份使用 22 端口。
* 发布的端口会监听所有接口。在云主机上，请绑定到 `127.0.0.1` 或使用 `-e UNSLOTH_STUDIO_SECURE=1`.
* JupyterLab 是一个完整的 shell。任何能够登录 JupyterLab 的人都可以在容器中运行任何命令。Unsloth Studio 和 JupyterLab 提供的是明文 HTTP，因此不要直接将它们暴露到互联网上。
* Unsloth Studio 工具可以运行代码。Studio 的服务端工具默认开启，并且可以在容器内运行命令。只挂载那些你愿意让容器访问的主机文件夹。
* 环境变量对 Docker 用户可见。通过 `-e` 或 `--env-file`传递的值，包括令牌和密码，会出现在 `docker inspect`中。任何可以访问 Docker 守护进程的人都能读取它们。


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://unsloth.ai/docs/zh/kuai-su-kai-shi/install/docker.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.