MT Container Toolkit 安装指南
MT Container Toolkit 是摩尔线程提供的容器运行时套件，用于在容器环境中使用摩尔线程 GPU 设备。本文档介绍支持的平台和详细的安装步骤。
注意：如果您计划使用 MT GPU Operator（Full 模式），可使用其自动安装 Linux 驱动、MTML、MT Container Toolkit 的功能。但仍需要关注本文档中的硬件及平台支持范围，以及依赖组件的版本。
硬件及平台支持
GPU 支持列表
MTT S5000
CPU 及 OS 支持
| CPU | OS |
|---|---|
| Intel | Ubuntu 22.04 |
| Intel | Alibaba Cloud Linux 3 (Soaring Falcon) |
| Intel | VesselOS 2.0 (LTS-SP2) |
| Intel | Debian 12 |
| AMD64 | Ubuntu 22.04 |
| Hygon4 | Ubuntu 22.04 |
| Hygon4 | Kylin V10/V11 |
系统依赖组件
在开始安装 MT Container Toolkit 之前，请确保您的系统满足以下先决条件：
- GPU 驱动：已为您的宿主机安装了 MUSA Linux Driver。
注意：该版本 Container Toolkit 支持 MUSA SDK
4.3.x，5.1.x，5.2.x。故而依赖的 Linux Driver 版本为3.3.x，5.1.x，5.2.x。
您可以通过以下命令来验证显卡驱动是否正确安装：
❯ mthreads-gmi
Fri May 16 10:41:32 2026
---------------------------------------------------------------------
mthreads-gmi:2.3.2 Driver Version:3.3.5-server
---------------------------------------------------------------------
ID Name |PCIe |%GPU Mem
0 MTT S5000 |00000000:03:00.0 |0% 1428MiB(81920MiB)
...
---------------------------------------------------------------------
- GPU管理库 MTML：已为宿主机系统安装了摩尔线程 GPU 管理库(MT GPU Management Library)。安装包下载及操作指导参考安装 MTML。
注意：MTML 版本要求为
v2.2.0或v2.1.0。
- 容器引擎：已为系统配置了容器引擎，例如 Docker CE/EE、containerd 或 CRI-O。支持的容器运行时版本如下：
| 容器运行时名称及版本 | amd64 / x86_64 |
|---|---|
| Docker 20.10 | Y |
| containerd 1.5 ~ 2.1.0 | Y |
| CRI-O 1.21 | Y |
安装指导
安装容器运行时套件
在 Container-Toolkit 目录中包含 deb 和 rpm 两个文件夹，请根据您的 Linux 发行版选择对应的安装包。
Debian/Ubuntu 系列
$ sudo dpkg -i mt-container-toolkit_2.1.0-1_amd64.deb
CentOS/RHEL 系列
$ sudo rpm -ivh mt-container-toolkit-2.1.0-1.x86_64.rpm
设置默认的容器运行时
根据当前机器安装 的容器运行时选择合适的设置命令。
容器运行时为 Docker
绑定摩尔线程容器运行时到 Docker，设置默认的容器运行时为 mthreads 并重启 Docker daemon：
$ (cd /usr/bin/musa && sudo ./docker setup $PWD)
您可以通过如下命令检查默认的容器运行时是否已成功替换：
$ cat /etc/docker/daemon.json | grep default-runtime
"default-runtime": "mthreads",
您可以通过如下命令验证上述步骤是否成功，正常情况可以看到在容器内部已经能够获取到摩尔线程 GPU 设备。
❯ docker run --rm --env MTHREADS_VISIBLE_DEVICES=all ubuntu:22.04 mthreads-gmi
Fri May 16 02:42:24 2025
---------------------------------------------------------------
mthreads-gmi:2.0.0 Driver Version:3.0.0
---------------------------------------------------------------
ID Name |PCIe |%GPU Mem
Device Type |Pcie Lane Width |Temp MPC Capable
| ECC Mode
+-------------------------------------------------------------+
0 MTT S80 |00000000:01:00.0 |0% 516MiB(16384MiB)
Physical |16x(16x) |60C YES
| N/A
---------------------------------------------------------------
---------------------------------------------------------------
Processes:
ID PID Process name GPU Memory
Usage
+-------------------------------------------------------------+
No running processes found
---------------------------------------------------------------
容器运行时为 Containerd
绑定摩尔线程容器运行时到 Containerd，设置默认的容器运行时为 mthreads 并重启 Containerd：
$ (cd /usr/bin/musa && sudo ./containerd setup $PWD)
您可以通过如下命令检查默认的容器运行时是否已成功替换：
$ cat /etc/containerd/config.toml | grep default_runtime_name
default_runtime_name = "mthreads"
您可以通过如下命令验证上述步骤是否成功，正常情况可以看到在容器内部已经能够获取到摩尔线程 GPU 设备。
❯ ctr run --rm --env MTHREADS_VISIBLE_DEVICES=all ubuntu:22.04 test-container mthreads-gmi
Fri May 16 02:42:24 2025
---------------------------------------------------------------
mthreads-gmi:2.0.0 Driver Version:3.0.0
---------------------------------------------------------------
ID Name |PCIe |%GPU Mem
Device Type |Pcie Lane Width |Temp MPC Capable
| ECC Mode
+-------------------------------------------------------------+
0 MTT S80 |00000000:01:00.0 |0% 516MiB(16384MiB)
Physical |16x(16x) |60C YES
| N/A
---------------------------------------------------------------
---------------------------------------------------------------
Processes:
ID PID Process name GPU Memory
Usage
+-------------------------------------------------------------+
No running processes found
---------------------------------------------------------------
卸载指南
恢复容器运行时默认配置
如果您使用的是 Docker 环境，需要恢复 Docker 默认的容器运行时并重启 Docker daemon：
$ (cd /usr/bin/musa && sudo ./docker cleanup $PWD)
如果您使用的是 Containerd 环境，需要恢复 Containerd 默认的容器运行时并重启 Containerd：
$ (cd /usr/bin/musa && sudo ./containerd cleanup $PWD)
卸载软件包并清除配置
Debian/Ubuntu 系列
$ sudo dpkg -r mt-container-toolkit
# 完全卸载并清除配置文件
$ sudo dpkg -P mt-container-toolkit
CentOS/RHEL 系列
$ sudo rpm -e mt-container-toolkit
# 查找并清除配置文件
$ sudo rpm -qc mt-container-toolkit
$ sudo rm -rf /etc/包名/
故障排查
验证驱动状态
如果遇到问题，请首先验证摩尔线程驱动是否正常工作，版本符合软件要求：
$ mthreads-gmi
如果命令无法执行或显示错误信息，请检查：
- 显卡驱动是否正确安装
- 显卡硬件是否被系统识别
- 系统日志中是否有相关错误信息
验证容器运行 时配置
确认容器运行时配置文件中已正确设置 mthreads 为默认运行时：
Docker：
$ sudo cat /etc/docker/daemon.json
Containerd：
$ sudo cat /etc/containerd/config.toml
