nvtop 3.3.2 常用 CLI 命令与工具详解

目标：把 nvtop 的命令行用法一次讲全——nvtop 是"单命令 + 丰富参数 + 键盘交互"的 TUI 工具，没有子命令体系；本文覆盖全部启动参数的实测回显与语义、运行中的按键操作（排序/选进程/发信号/界面定制）、多 GPU 视图管理、-s/-l 脚本化采集，以及与 nvidia-smi 的配合分工。全部命令与输出在 Ubuntu 22.04 逐条实测照抄；本实验机无 GPU，无 GPU 时的真实启动表现专节如实记录（这正是把 nvtop 装上普通云主机/物理服务器后最容易遇到的第一屏）。

一、环境信息

• 操作系统：Ubuntu 22.04（jammy，x86_64），内核 5.15 系列
• nvtop 版本：3.3.2（源码 tag 3.3.2，commit 76890233d；另含 1.2.2 对照实测）
• 安装形态：源码编译版 /usr/local/bin/nvtop（3.3.2）与 PPA 版 /usr/bin/nvtop（3.3.2-1+jammy）双环境实测；安装见站内《Ubuntu 22.04 安装 nvtop 3.3.2 指南》
• GPU：无（无 GPU 行为实测与有 GPU 界面描述分别处理，后者标注官方来源）
• 手册：man nvtop（nvtop(1)，随安装分发）
• 溯源日期：2026-10-23

二、工具概览

nvtop 家族的"工具集"很紧凑，共四件：

💡 技术拓展：同为"终端监控"，nvtop 与 htop 系工具的命令面结构不同——htop/btop 只需启动没有查询子命令，而 nvtop 因为要兼顾"看一眼就走的脚本场景"，把快照（-s）与循环（-l）做成了无界面输出模式。这使它能扮演两类角色：交互观察器（默认）与数据采集端（-s/-l），后者是与 nvidia-smi 查询模式互补的关键。

三、前置条件

• nvtop 已安装并通过 nvtop --version 验证（实测输出 nvtop version 3.3.2）；
• $TERM 为有效终端类型：echo $TERM 应输出 xterm-256color 一类有效值；无效时（有 GPU 机器上）会报 ncurses: cannot initialize terminal type ($TERM="unknown")（官方 README Troubleshoot）；
• NVIDIA 机器需驱动就绪：ldconfig -p | grep nvidia-ml 应能看到 libnvidia-ml.so.1——未装驱动的机器实测 nvidia-smi 直接 command not found（退出码 127），nvtop 侧则只显示 No GPU to monitor.；
• Intel 机器读总显存/精确频率需 root 或 sudo setcap cap_perfmon=ep $(which nvtop)（官方 README Intel 节）；
• 无 GPU 机器：所有安装与参数验证可完整进行，仅无监控画面（见第六节）。

四、启动参数详解（逐项实测）

nvtop -h 实测回显（Ubuntu 22.04，3.3.2，逐行照抄）：

nvtop version 3.3.2
Available options:
  -d --delay        : Select the refresh rate (1 == 0.1s)
  -v --version      : Print the version and exit
  -c --config-file  : Provide a custom config file location to load/save preferences
  -p --no-plot      : Disable bar plot
  -P --no-processes : Disable process list
  -r --reverse-abs  : Reverse abscissa: plot the recent data left and older on the right
  -C --no-color     : No colors
line information
  -f --freedom-unit : Use fahrenheit
  -i --gpu-info     : Show bar with additional GPU parameters
  -E --encode-hide  : Set encode/decode auto hide time in seconds (default 30s, negative = always on screen)
  -h --help         : Print help and exit
  -s --snapshot     : Output the current gpu stats without ncurses(useful for scripting)
  -l --loop         : Output the current gpu stats without ncurses in a loop

4.1 版本与帮助：-v / -h

nvtop --version

实测回显：

nvtop version 3.3.2

-h 回显见上。两参数在任何机器（含无 GPU）都可用，是部署后第一验证命令。

4.2 刷新间隔：-d（单位 0.1 秒）

nvtop -d 5     # 0.5 秒刷新，动画更流畅
nvtop -d 100   # 10 秒刷新，低功耗挂机

实测回显（无 GPU 机器，参数解析正常进入设备探测）：

No GPU to monitor.

说明：默认 1 秒（源码 update_interval = 1000 毫秒）。-d 与 F2 设置中的 update interval 等价（后者持久化，见《nvtop 3.3.2 配置参数详解》）。

4.3 快照输出：-s（脚本化首选）

nvtop -s
echo $?

实测回显：

No GPU to monitor.
0

无 GPU 机器上 -s 的输出就是这一行、退出码 0；有 GPU 的机器上，-s 会把每卡的利用率、显存、温度、功耗、时钟与进程信息以纯文本打印一次后退出（形态同官方 README 对 snapshot 的定位："Output the current gpu stats without ncurses (useful for scripting)"）。它不依赖 ncurses，cron/重定向/管道全部可用，是本文第七节采集方案的基座。

4.4 循环快照：-l

timeout 5 nvtop -l

实测回显（无 GPU）：

No GPU to monitor.

有 GPU 机器上 -l 以固定节奏持续打印快照（等价反复执行 -s），配合 timeout/head 可定量截取。区别于默认 TUI：全程无光标界面，输出即纯文本流。

4.5 界面裁剪：-p / -P / -i

• -p --no-plot：清空图表绘制区（源码 nvtop.c 292–296 行把每卡 to_draw 置 0），界面只剩设备条与进程列表——小窗口 SSH 里只看瞬时值时用；
• -P --no-processes：隐藏底部进程列表（进程多到刷屏、只想看卡况时用）；
• -i --gpu-info：打开附加信息栏。NVIDIA 机器上显示 NVML 不上报的动态时钟（XBAR/SYS/NVD），时钟域读 libnvidia-api.so.1；库缺失时其余界面不受影响、信息栏自动不留位（官方 README NVIDIA 节）。

组合实测（无 GPU，参数组合解析正常）：

nvtop -d 5 -C

No GPU to monitor.

4.6 显示细节：-C / -f / -r / -E

• -C --no-color：单色模式（远程老终端/日志归档友好）。源码彩蛋：长选项 --no-colour 是同义别名（src/nvtop.c 第 89 行 .name = "no-colour"），-h 未列出；
• -f --freedom-unit：温度华氏度显示（默认摄氏）；
• -r --reverse-abs：图表横轴反转，最新数据在左（默认最新在右）；
• -E --encode-hide <秒>：ENC/DEC 占用条闲置后隐藏的秒数，默认 30；负值（如 -E -1）表示编解码条常显（实测 -E -1 参数解析正常）。

4.7 配置文件位置：-c

nvtop -c /root/nvtop-ui.ini

把"加载偏好"与"F12 保存"都指向 /root/nvtop-ui.ini。实测（无 GPU）：

No GPU to monitor.

且该文件不会被创建（ls /root/nvtop-test.ini 实测 No such file or directory）——配置文件的生成时机是界面内按 F12（有 GPU 机器上）。多套界面偏好的玩法：alias nvtop-work='nvtop -c ~/.config/nvtop/work.ini'。

4.8 无效参数与未发布参数（排障实录）

nvtop --nonexist
echo $?

实测回显（3.3.2 与 1.2.2 一致）：

Unhandled error in getopt missing argument
1

⚠️ 两个实测发现：其一，未知长参数的报错文案是 "missing argument"（getopt 统一报错），看到它应先怀疑参数名拼错而非缺参；其二，官方 README 提到的 nvtop -X（静态规格栏：着色器核心/L2 缓存等）在 3.3.2 尚未落地——实测 nvtop -X 报同样错误、退出码 1，且源码 src/nvtop.c 的选项表（第 84–97 行）无 X 项。该能力属文档超前，升级版本后用 nvtop -h 重新确认再使用。

4.9 老版本 1.2.2 参数差异（速查）

1.2.2 的 -h 实测回显（节选）可对照确认：-s --gpu-select : Colon separated list of GPU IDs to monitor、-i --gpu-ignore : Colon separated list of GPU IDs to ignore。

五、键盘交互详解（TUI 内操作）

进入界面后全部操作走键盘（man 页 INTERACTIVE COMMANDS 节全表，配合源码核对）：

F2 setup 窗口四个分区的可调项（man 页 INTERACTIVE SETUP WINDOW 节）：

运行期动态行为：GPU 的编码（ENC）/解码（DEC）单元被占用时，利用率条旁会动态出现百分比条，闲置一段时间后自动消失（时长即 -E/EncodeHideTimer，man 页 DYNAMIC METERS 节）。内存单位一律 1024 进制 KiB（man 页 MEMORY SIZES 节）。

六、无 GPU 机器的真实行为（专节）

本节是实测结论，适用于"把 nvtop 装上没插卡、也没直通卡的服务器"这一常见场景：

nvtop; echo rc=$?

实测回显：

No GPU to monitor.
0

• 启动即检测不到任何受支持的 GPU/加速器时，nvtop 打印一行 No GPU to monitor. 后正常退出（退出码 0），不进界面、不报错、不挂起；
• -s、-l、任意参数组合在该机器上都是同一输出（4.3/4.4/4.5 实测一致）——参数解析先于设备探测报错；也正因如此，无 GPU 机器上不会触发 $TERM 类 ncurses 报错（那发生在界面初始化之后）；
• 排障含义：在本应有卡的机器上看到这行，顺序排查三件事——驱动装了吗（NVIDIA：ldconfig -p | grep nvidia-ml；未装驱动机器实测 nvidia-smi: command not found，退出码 127）、内核驱动加载了吗（AMD/Intel：lspci -k 看卡绑定的内核驱动）、编译开关对吗（源码版是否把对应后端编进去了，见 cmake .. -LH）。

七、有 GPU 界面预期与多 GPU 视图

界面预期（描述依据官方 README 首图 screenshot/NVTOP_ex1.png 与 man 页，2026-10-23；本文实验机无 GPU，不杜撰数值）：nvtop 为每块 GPU 显示一个分组——顶部是利用率/显存条与温度、功耗、风扇、时钟等数值行，中部是该卡的利用率折线图（默认绘制 GPU 利用率与显存利用率两条曲线），底部是全部 GPU 的进程合并列表（列含进程号、用户、卡号、类型、GPU 占用率、编码/解码率、显存等）。多卡机器自上而下排列多个分组，同一屏尽收。

多 GPU 视图管理：

1. 默认全卡监控：无需参数，启动即列出全部探测到的设备；
2. 会话内开关某张卡：F2 的 Devices 分区配合每卡设置；持久化落在 interface.ini 的 [Device] 节（Pdev 标识卡、Monitor=true|false 控制监控、ShownInfo 控制该卡图表指标——源码 interface_options.c 第 189–193 行）。程序保证至少一张卡处于监控状态（源码 interface_check_and_fix_monitored_gpus()：全关时强制恢复一张）；
3. 老版本选卡：1.2.2 用 -s <id逗号列表> 选卡、-i <id列表> 忽略卡（见 4.9 速查表）；
4. 多卡采集：-s 快照输出覆盖全部卡，按卡分块打印，脚本侧按块解析即可。

八、与 nvidia-smi 的配合

nvtop 与 nvidia-smi 是互补而非替代关系（NVIDIA 环境）：

一条实用的就绪自检链（有 NVIDIA 卡的机器上按序执行）：

nvidia-smi >/dev/null 2>&1 && echo driver-ok || echo driver-missing
ldconfig -p | grep nvidia-ml | head -1
nvtop -s | head -5

三步全过（driver-ok、libnvidia-ml.so.1 在列、快照有内容）说明"驱动 → NVML → nvtop"链路贯通；任何一步失败，nvtop 都只会给出 No GPU to monitor.，用上一步的输出定位断点。

九、注意事项

1. 版本语义陷阱：-s/-i 在 1.2.2 与 3.x 含义完全不同（4.9 表），混管老机器时先 nvtop --version 再套命令；
2. -X 文档超前：官方 README 提及但 3.3.2 未实现（4.8 实测），勿按文档硬敲；
3. 快照退出码恒 0：无 GPU 的 No GPU to monitor. 也是 0（第六节实测）——采集脚本必须校验输出内容而非只看退出码；
4. 权限：Intel 卡的显存总量/频率需 CAP_PERFMON/CAP_SYS_ADMIN；snap 安装形态还需要 snap connect 一组接口（官方 README Snap 节）；
5. 字段 N/A 属正常：厂商驱动不提供的指标显示 N/A（man 页 BUGS 节：AMD/NVIDIA 老卡升级内核或换驱动可改善）；
6. 配置文件别手编：interface.ini 是 F12 的输出物，键值白名单硬解析，预置走"真机导出分发"（见《nvtop 3.3.2 配置参数详解》第七节）。

十、常见问题（FAQ）

Q1：nvtop 装好后运行没反应/只打一行字？ 先看是不是无卡机器——No GPU to monitor. 且 rc=0 是无卡机器的标准输出（第六节）。有卡的机器按第六节排障链查驱动与内核绑定。

Q2：SSH 里图表错乱或看不到颜色？ 确认 $TERM 有效（xterm-256color）；需要单色用 -C；图表字符渲染异常通常是编译时缺宽字符 ncurses，重装 libncursesw5-dev 后清空 build 目录重编（官方 README Troubleshoot）。

Q3：F9 想杀进程，怎么选信号？ F9 后会弹出信号选择菜单（man 页：'"Kill" process: Select a signal to send to the highlighted process'），常用 SIGTERM/SIGKILL 按提示选择；nvtop 默认会在进程列表中过滤自身进程（源码 filter_nvtop_pid = true），不会误杀自己。

Q4：nvtop -s 输出能直接进 Prometheus 吗？ 不能直接进，它面向人读。要接监控系统，用 nvidia-smi 的 --query-gpu CSV、DCGM-exporter 等专用采集器；nvtop 的角色是交互观察与轻量留档（cron + -s 追加日志）。

Q5：同一台机器装了 PPA 版和源码版，运行的是哪个？ type -a nvtop 查看全部路径与生效顺序（源码版默认 /usr/local/bin 优先于 /usr/bin）；指定版本可用全路径执行。

十一、参考链接

• man 手册 nvtop(1)（INTERACTIVE COMMANDS / INTERACTIVE SETUP WINDOW / DYNAMIC METERS / MEMORY SIZES / BUGS 节）
• 官方 README（Options and Interactive Commands / GPU Support / Troubleshoot）：https://github.com/Syllo/nvtop （查询日期 2026-10-23）
• 源码 3.3.2 选项表：https://github.com/Syllo/nvtop/blob/3.3.2/src/nvtop.c （第 84–97 行 getopt 定义）
• 站内系列：《nvtop 介绍与选型指南》《Ubuntu 22.04 安装 nvtop 3.3.2 指南》《nvtop 3.3.2 配置参数详解》