# 通过 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):
export NVIDIA_CONTAINER_TOOLKIT_VERSION=1.17.8-1
sudo apt-get update && 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}
{% 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
```
{% endstep %}
{% step %}
**访问 Jupyter Lab**
前往 [http://localhost:8888](http://localhost:8888/) 并打开 Unsloth。
访问 `unsloth-notebooks` 标签页以查看 Unsloth 笔记本。
{% endstep %}
{% step %}
**开始使用 Unsloth 训练**
如果你是新手，请按照我们的分步 [微调指南](https://unsloth.ai/docs/zh/kai-shi-shi-yong/fine-tuning-llms-guide), [RL 指南](https://unsloth.ai/docs/zh/kai-shi-shi-yong/reinforcement-learning-rl-guide) 或者直接保存/复制我们任何预制的 [笔记本](https://unsloth.ai/docs/zh/kai-shi-shi-yong/unsloth-notebooks).
{% 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`
* 参照：
### ⚙️ 高级设置
```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 :
```
* Jupyter Lab： `-p 8000:8888`
* SSH 访问： `-p 2222:22`
{% hint style="warning" %}
**重要**：使用卷挂载以在容器运行之间保留你的工作。
{% endhint %}
```bash
-v :
```
```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 访问需要公钥认证
