# 通过 Docker 安装 Unsloth

了解如何使用我们的 Docker 容器，所有依赖均已预装，可立即安装。无需设置，只需运行并开始训练！

Unsloth Docker 镜像： [**`unsloth/unsloth`**](https://hub.docker.com/r/unsloth/unsloth)

{% hint style="success" %}
Unsloth Studio 现在与笔记本和脚本共享相同的缓存，以避免不必要的重复下载。
{% endhint %}

### ⚡ 快速开始

{% stepper %}
{% step %}
**安装 Docker 和 NVIDIA Container Toolkit。**

通过以下方式安装 Docker [Linux](https://docs.docker.com/engine/install/) 或 [桌面版](https://docs.docker.com/desktop/) （其他）。\
然后安装 [NVIDIA Container Toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html#installation):

<pre class="language-bash"><code class="lang-bash"><strong>export NVIDIA_CONTAINER_TOOLKIT_VERSION=1.17.8-1
</strong>sudo apt-get update &#x26;&#x26; sudo apt-get install -y \
  nvidia-container-toolkit=${NVIDIA_CONTAINER_TOOLKIT_VERSION} \
  nvidia-container-toolkit-base=${NVIDIA_CONTAINER_TOOLKIT_VERSION} \
  libnvidia-container-tools=${NVIDIA_CONTAINER_TOOLKIT_VERSION} \
  libnvidia-container1=${NVIDIA_CONTAINER_TOOLKIT_VERSION}
</code></pre>

<figure><img src="/files/8f3bf33c47ce755d8b292f85bff67057bfda2bd8" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}
**运行容器。**

[**`unsloth/unsloth`**](https://hub.docker.com/r/unsloth/unsloth) 是 Unsloth 唯一的 Docker 镜像。

```bash
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
```

<figure><img src="/files/2a98185266756c4ff5716bd5411c5d981624317f" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}
**访问 Jupyter Lab**

前往 [http://localhost:8888](http://localhost:8888/) 并打开 Unsloth。

<figure><img src="/files/4fc869e28f370e86f0135d389a3b871b734b5fb4" alt="" width="563"><figcaption></figcaption></figure>

访问 `unsloth-notebooks` 标签页以查看 Unsloth 笔记本。

<div><figure><img src="/files/ad4f85d926c69021aeccd88f5ff808d33c7c5a04" alt=""><figcaption></figcaption></figure> <figure><img src="/files/5c5dfcf0c52fa315849e660f8c35b61109e8cfcc" alt=""><figcaption></figcaption></figure></div>
{% endstep %}

{% step %}
**开始使用 Unsloth 训练**

如果你是新手，请按照我们的分步 [微调指南](/docs/zh/kai-shi-shi-yong/fine-tuning-llms-guide.md), [RL 指南](/docs/zh/kai-shi-shi-yong/reinforcement-learning-rl-guide.md) 或者直接保存/复制我们任何预制的 [笔记本](/docs/zh/kai-shi-shi-yong/unsloth-notebooks.md).

<figure><img src="/files/b7da0983149ef6f31b9dfe456afe367682a6d019" alt=""><figcaption></figcaption></figure>
{% endstep %}
{% endstepper %}

#### 📂 容器结构

* `/workspace/work/` — 你挂载的工作目录
* `/workspace/unsloth-notebooks/` — 示例微调笔记本
* `/home/unsloth/` — 用户主目录

### 📖 使用示例

#### 完整示例

```bash
docker run -d -e JUPYTER_PORT=8000 \
  -e JUPYTER_PASSWORD="mypassword" \
  -e "SSH_KEY=$(cat ~/.ssh/container_key.pub)" \
  -e USER_PASSWORD="unsloth2024" \
  -p 8000:8000 -p 2222:22 \
  -v $(pwd)/work:/workspace/work \
  --gpus all \
  unsloth/unsloth
```

#### 设置 SSH 密钥

如果你没有 SSH 密钥对：

```bash
# 生成新的密钥对
ssh-keygen -t rsa -b 4096 -f ~/.ssh/container_key

# 在 docker run 中使用公钥
-e "SSH_KEY=$(cat ~/.ssh/container_key.pub)"

# 通过 SSH 连接
ssh -i ~/.ssh/container_key -p 2222 unsloth@localhost
```

### 🦥为什么选择 Unsloth 容器？

* **可靠**：精心维护的环境，拥有稳定且受维护的软件包版本。压缩后仅 7 GB（而其他地方为 10–11 GB）
* **即用型**：预装在中的笔记本 `/workspace/unsloth-notebooks/`
* **安全**：以非 root 用户身份安全运行
* **通用**：兼容所有基于 transformer 的模型（TTS、BERT 等）

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

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

手动拉取最新镜像：

```bash
 docker pull unsloth/unsloth:latest
```

* 使用 GPU 访问启动容器：
  * `docker run`: `--gpus all`
  * Docker Compose： `capabilities: [gpu]`
* 在 Linux 上，请确保已安装 NVIDIA Container Toolkit。
* 在 Windows 上：
  * 检查 `nvcc --version` 是否与以下内容中显示的 CUDA 版本匹配 `nvidia-smi`
  * 参照： <https://docs.docker.com/desktop/features/gpu/>

### ⚙️ 高级设置

```bash
# 生成 SSH 密钥对
ssh-keygen -t rsa -b 4096 -f ~/.ssh/container_key

# 连接到容器
ssh -i ~/.ssh/container_key -p 2222 unsloth@localhost
```

| 变量                 | 描述                     | 默认值       |
| ------------------ | ---------------------- | --------- |
| `JUPYTER_PASSWORD` | Jupyter Lab 密码         | `unsloth` |
| `JUPYTER_PORT`     | 容器内的 Jupyter Lab 端口    | `8888`    |
| `SSH_KEY`          | 用于身份验证的 SSH 公钥         | `无`       |
| `USER_PASSWORD`    | 的密码 `unsloth` 用户（sudo） | `unsloth` |

```bash
-p <host_port>:<container_port>
```

* Jupyter Lab： `-p 8000:8888`
* SSH 访问： `-p 2222:22`

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

```bash
-v <local_folder>:<container_folder>
```

```bash
docker run -d -e JUPYTER_PORT=8000 \
  -e JUPYTER_PASSWORD="mypassword" \
  -e "SSH_KEY=$(cat ~/.ssh/container_key.pub)" \
  -e USER_PASSWORD="unsloth2024" \
  -p 8000:8000 -p 2222:22 \
  -v $(pwd)/work:/workspace/work \
  --gpus all \
  unsloth/unsloth
```

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

* 容器默认以非 root `unsloth` 用户运行
* 使用 `USER_PASSWORD` 在容器内执行 sudo 操作
* SSH 访问需要公钥认证


---

# Agent Instructions: 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:

```
GET https://unsloth.ai/docs/zh/kai-shi-shi-yong/install/docker.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.