nvtop 3.3.2 配置参数详解

nvtop 3.3.2 配置参数详解：四层配置体系（编译期 CMake 选项、命令行参数、F2 交互设置、F12 持久化 interface.ini 全键位），环境变量与默认值逐项说明，配场景化配置模板与 FAQ，参数值均经实测与源码核对。

nvtopGPU 监控性能监控2026/10/23

nvtop 3.3.2 配置参数详解

目标：把 nvtop 3.3.2 的全部可配置项一次讲清——它没有传统服务端那种主配置文件，配置分四层落地：编译期 CMake 选项（决定支持哪些厂商硬件）、命令行参数（单次运行行为）、运行中 F2 交互设置（会话内调整）、F12 保存的 interface.ini（持久化界面偏好）。本文每张参数表都来自 Ubuntu 22.04 实测回显或对 3.3.2 源码的逐行核对，安装过程见站内《Ubuntu 22.04 安装 nvtop 3.3.2 指南》。

一、环境信息

  • 操作系统：Ubuntu 22.04（jammy，x86_64）
  • nvtop 版本：3.3.2（源码 commit 76890233d759199f50ad3bdb57a0c0988e96fc44，tag 3.3.2，2026-02-08）
  • 参照老版本：1.2.2（Ubuntu 22.04 发行版仓库自带，用于版本差异对照）
  • 溯源与核对日期：2026-10-23（官方 README/man 页/源码 src/）
  • 硬件说明：实验机器无 GPU——nvtop 的配置项、帮助文本、配置文件路径与版本行为均可完整验证；仅"图块显示效果"一节依据官方文档描述并标注来源。

二、前置条件

  • 已按《Ubuntu 22.04 安装 nvtop 3.3.2 指南》装好 nvtop 并通过 nvtop --version 验证（实测输出 nvtop version 3.3.2）；
  • 查看编译期选项需要源码树与 cmake（cmake .. -LH），只看运行期参数则只需可执行的 nvtop 与 nvtop -h；
  • 若要核对 interface.ini 键名，需要解包源码（git clone 后 src/interface_options.c）；
  • 无 GPU 的机器上 nvtop 启动会输出 No GPU to monitor. 后退出（实测，退出码 0）——这不影响 -h/--version 等参数验证。

三、参数查看与修改方式

nvtop 的配置入口有四个，修改优先级与生效时长各不相同（依据 man 页 CONFIGURATION FILE/INTERACTIVE SETUP WINDOW 节与源码 src/nvtop.c 参数处理逻辑）：

层级入口生效范围查看方法
编译期CMake 选项（如 -DNVIDIA_SUPPORT=ON）决定二进制支持哪些硬件后端，改后需重新编译cmake .. -LH（源码树内）
命令行nvtop -d/-p/-P/-i/-E/-c/-s/-l/-r/-C/-f仅本次运行nvtop -h
会话内交互界面内按 F2（setup 窗口）仅本次运行，F12 前不持久界面内查看
持久化F12 保存 → interface.ini每次启动自动加载cat ~/.config/nvtop/interface.ini

配置文件定位规则（源码 src/interface_options.c 第 37–58 行核对）：固定相对路径 nvtop/interface.ini；目录取 $XDG_CONFIG_HOME，未设置则回退 $HOME/.config；-c <路径> 可整体替换该文件位置。程序启动时加载，interface.ini 不存在时全部用内置默认值。

⚠️ 官方立场：man 页明确 "Do not edit this file. The file is automatically created or updated upon toggling the interface saving key F12."——interface.ini 是 F12 的输出物而非手写配置；需要默认行为差异时用命令行参数或写 shell alias，不要手编 ini。

四、编译期参数总览（CMake 选项）

以下为 3.3.2 源码 CMakeLists.txt 与 cmake .. -LH 实测结果（配置命令 cmake .. -DNVIDIA_SUPPORT=ON -DAMDGPU_SUPPORT=ON -DINTEL_SUPPORT=ON -DCMAKE_BUILD_TYPE=Release，回显见安装指南 7.3 节）：

选项类型Linux 默认值说明
NVIDIA_SUPPORTBOOLON通过 libnvml 支持 NVIDIA GPU
AMDGPU_SUPPORTBOOLON通过 amdgpu 驱动支持 AMD GPU
INTEL_SUPPORTBOOLON通过 i915/xe 驱动支持 Intel GPU
MSM_SUPPORTBOOLON通过 msm 驱动支持 Adreno（高通）GPU
V3D_SUPPORTBOOLON支持 Broadcom VideoCore（树莓派）
PANFROST_SUPPORT / PANTHOR_SUPPORTBOOLONARM Mali GPU（Panfrost/Panthor 驱动）
METAX_SUPPORTBOOLONMetaX GPU（MXSML 库）
ASCEND_SUPPORTBOOLOFF昇腾 NPU（Ascend DCMI）——唯一默认关闭的主力后端，启用需显式 -DASCEND_SUPPORT=ON
TPU_SUPPORTBOOL自动探测Google TPU（GRPC），检测到 libtpuinfo.so 才开
APPLE_SUPPORTBOOLOFF（Linux）Apple Metal（仅 macOS 构建且独占）
BUILD_TESTINGBOOLOFF单元测试（依赖 GTest）
USE_LIBUDEV_OVER_LIBSYSTEMDBOOLOFF设备枚举：默认用 libsystemd，置 ON 强制 libudev
CMAKE_BUILD_TYPESTRING无（建议显式 Release）Release=无调试信息；RelWithDebInfo=带调试信息；Debug=开警告与地址/UB 消毒器（开发用，官方 README 说明）
CMAKE_INSTALL_PREFIXPATH/usr/local安装前缀；多版本共存时改此值（如 /opt/nvtop-3.3.2）
ASCEND_ROOTPATH无昇腾 CANN 安装在非标准位置时指定（官方 README：-DASCEND_ROOT=/path/to/Ascend）

两点实测细节值得注意：

  1. 默认开关随平台变化：源码 CMakeLists.txt 第 64–89 行按平台分支设定默认值——Linux 非 Apple/非昇腾构建时 NVIDIA/AMDGPU/INTEL/V3D/MSM/PANFROST/PANTHOR/METAX 全部默认 ON，仅 ASCEND 默认 OFF；Apple 平台则只默认开 APPLE_SUPPORT。因此"裸 cmake .. 即得全厂商版"在 Linux 上成立，显式传三大 -D*_SUPPORT=ON 是官方 README 给出的稳妥写法。
  2. TPU/Enflame 按依赖探测：CMakeLists.txt 对 Linux 上的 libtpuinfo.so（TPU）与 Enflame GCU 库做 find_library 探测，找到才默认启用——编译机上没有厂商库就不会编进对应后端。

五、命令行参数详解（运行期）

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

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

逐项说明（默认值取自源码 src/interface_options.c 的 alloc_interface_options_internals() 与 man 页）：

参数默认值说明与注意
-d <delay>10（即 1 秒，源码 update_interval = 1000 毫秒）刷新间隔，单位 0.1 秒：-d 5 = 0.5s、-d 100 = 10s
-v—打印版本退出（实测输出 nvtop version 3.3.2）
-c <file>空（走 XDG 默认路径）指定配置文件位置，加载与 F12 保存都用它
-p不隐藏（图表区默认绘制）清空每卡图表绘制项（源码 nvtop.c 第 292–296 行：把 to_draw 置 0），只留设备条与进程列表
-P不隐藏隐藏底部进程列表
-r关（图表默认"旧→新"从左到右，源码 plot_left_to_right = false）反转横轴：新数据在左
-C关（use_color = true）单色模式
-f关（temperature_in_fahrenheit = false，摄氏度）华氏度显示
-i关（has_gpu_info_bar = false）附加 GPU 信息栏：显示 NVML 不上报的动态时钟（XBAR/SYS/NVD）；静态规格需 -X（man 页/README 提及），时钟域读 libnvidia-api.so.1，库缺失时该栏自动不留位
-E <seconds>30（encode_decode_hiding_timer = 30.）ENC/DEC 占用条闲置后自动隐藏的秒数；负数常显
-s—快照模式：打印一次状态后退出，不进 ncurses
-l—循环快照模式（同样无 ncurses），适合管道采集
-h—帮助（注意帮助文本中 -C 下一行的 line information 是换行续排的 "No colors / line information"，实测原样）

与 1.2.2 的参数差异（1.2.2 -h 实测对照，老环境运维必读）：

参数1.2.2 含义3.3.2 含义
-s--gpu-select：选卡（需参数，实测缺参报 Unhandled error in getopt missing argument）--snapshot：快照输出（无参数）
-i--gpu-ignore：忽略指定卡--gpu-info：附加信息栏
-P不存在（1.2.2 实测报 missing argument）隐藏进程列表
-l不存在循环快照
-c存在，同义同义

无 GPU 机器上实测：nvtop -s、nvtop -l、nvtop -s 0（1.2.2 的选卡写法）均输出 No GPU to monitor. 且退出码 0——快照参数先于界面初始化生效，行为一致。

六、运行中交互设置（F2 setup 窗口）与快捷键

有 GPU 的机器进入界面后，F2 打开 setup 窗口，四个分区对应四组设置（man 页 INTERACTIVE SETUP WINDOW 节原文归纳）：

分区可调项对应默认值
GeneralColor support（颜色开关）、interface update interval（刷新间隔）颜色开；1000ms
Devices华氏/摄氏切换、编码/解码隐藏计时、GPU 信息栏开关摄氏；30s；信息栏关
Chart图表方向反转、绘制指标选择（GPU/显存利用率、温度、功耗、时钟、PCIe 收发吞吐）不反转；默认绘制利用率与显存利用率
Processes排序开关与方向、排序字段、显示字段按显存降序（源码 sort_processes_by = process_memory、sort_descending_order = true）

运行中快捷键（man 页 INTERACTIVE COMMANDS 节全表）：

按键作用
Up / Down上/下选中进程
Left / Right进程行内横向滚动
+ / -升序 / 降序排序
F2打开 setup 窗口
F12保存当前界面偏好到 interface.ini
F9向选中进程发送信号（如终止）
F6选择排序字段（当前排序字段在表头高亮）
F10 / q / Esc退出

其他运行期机制：ENC/DEC 占用条在使用时动态出现、闲置按 -E 时长自动隐藏（man 页 DYNAMIC METERS 节）；内存单位一律 1024 进制（man 页 MEMORY SIZES 节："Memory sizes in nvtop are displayed as multiples of 1024 bytes or 1 KiB"）。

七、持久化配置：interface.ini 全键位

F12 保存的文件按 XDG 规范落在 $XDG_CONFIG_HOME/nvtop/interface.ini（默认 ~/.config/nvtop/interface.ini）；-c 指定路径时则写到指定位置。文件由程序自动创建/更新（目录递归创建，源码 create_config_directory_rec()），首行固定注释 ; Please do not edit this file.。

键位清单（源码 src/interface_options.c 第 158–196 行常量定义核对，3.3.2 完整集合）：

[GeneralOption]
UseColor=true|false              ; 颜色开关，默认 true
UpdateInterval=<整数毫秒>         ; 刷新间隔，默认 1000
ShowInfoMessages=true|false      ; 启动信息提示，默认 true

[HeaderOption]
UseFahrenheit=true|false         ; 温度单位，默认 false（摄氏）
EncodeHideTimer=<秒，可负>        ; ENC/DEC 条隐藏计时，默认 30
GPUInfoBar=true|false            ; 附加信息栏，默认 false

[ChartOption]
ReverseChart=true|false          ; 图表方向，默认 false

[ProcessListOption]
HideNvtopProcessList=true|false  ; 隐藏 nvtop 自身进程列表项
HideNvtopProcess=true|false      ; 过滤 nvtop 进程（默认 filter_nvtop_pid=true）
SortBy=<见下表>                   ; 排序字段，默认 memory
DisplayField=<逗号分隔的字段>      ; 显示字段集合
SortOrder=descending|ascending   ; 排序方向，默认 descending

[Device]                          ; 每卡一节
Pdev=<PCI 设备地址>               ; 卡标识
Monitor=true|false                ; 是否监控该卡（保持至少一张卡被监控）
ShownInfo=<见下表>                ; 该卡图表显示的指标集合

SortBy 合法值（源码 process_sortby_vals 数组原文）：pId, user, gpuId, type, gpuRate, encRate, decRate, memory, cpuUsage, cpuMem, cmdline, none。

ShownInfo 合法值（源码 device_draw_vals 数组原文）：gpuRate, gpuMemRate, encodeRate, decodeRate, temperature, powerDrawRate, fanSpeed, gpuClockRate, gpuMemClockRate, effectiveLoadRate, none。

实测验证（无 GPU 机器）：运行 nvtop -c /root/nvtop-test.ini 在检测不到卡时直接退出，不会生成配置文件（ls /root/nvtop-test.ini 实测 No such file or directory）——配置文件只在界面内按 F12 或程序正常初始化界面后由程序写入。因此持久化配置的首次生成必须在有 GPU 的机器上完成。

💡 技术拓展：interface.ini 是 INI 格式，但键值语义由程序硬编码解析（ini_parse_file + 固定 section/key 常量），手写非法值不会报错而是被忽略并回落默认——这也是官方"别手编"的原因。若确需批量预置（如给 50 台训练机统一界面），做法是：先在一台有卡的机器上按 F12 调好并保存，再把生成的 interface.ini 分发到各机的 ~/.config/nvtop/（或配合 -c 指到统一挂载路径），比手写键值可靠。

八、环境变量与运行前提

nvtop 读取的环境变量与外部条件（全部有官方文档或源码依据）：

变量/条件作用来源
TERM必须为有效终端类型（如 xterm-256color），否则报 ncurses: cannot initialize terminal type ($TERM="unknown")（仅在能进界面时触发）官方 README Troubleshoot
XDG_CONFIG_HOME配置文件根目录；未设置回退 $HOME/.config源码 default_config_path()
HOMEXDG 未设置时的回退依据同上
LD_LIBRARY_PATH影响 dlopen 查找 libnvidia-ml.so/libnvidia-ml.so.1——NVIDIA 机器上该库缺失/不可见即报 No GPU to monitor.源码 extract_gpuinfo_nvidia.c 第 275/277 行
PATHAppImage 直跑需要 fusermount 在 PATH 中实测报错 No suitable fusermount binary found on the $PATH
CAP_PERFMON/CAP_SYS_ADMINIntel 卡读总显存与精确频率需要（root 或 setcap cap_perfmon=ep $(which nvtop)）官方 README Intel 节

九、场景化配置模板

nvtop 无服务端主配置，"生产模板"落地为命令行用法约定 + 预置偏好文件两件套。以下三个场景直接可用（路径与账号均落实际值，本例以 root 用户为例）：

场景一：训练服务器 SSH 常驻观察（16GB 内存小机也适用，nvtop 自身内存占用极低）

# ~/.bashrc 追加别名：1 秒刷新 + 显示附加信息栏 + 华氏度关闭（默认摄氏）
alias nvtop='command nvtop -i'

说明：-i 附加栏对 NVIDIA 机器展示 XBAR/SYS/NVD 时钟；不额外加 -d，默认 1s 刷新对 GPU 利用率曲线已足够平滑。

场景二：定时采集进监控脚本（cron 每 5 分钟留一份快照）

# crontab -e 追加（root 用户，密码策略同系统规范，示例目录提前 mkdir -p /var/log/gpu-snap）
*/5 * * * * /usr/local/bin/nvtop -s >> /var/log/gpu-snap/snapshot.log 2>&1

说明：-s 快照模式无 ncurses 依赖、可直接重定向；比 -l 常驻循环更省心（无进程存活管理问题）。

场景三：统一界面偏好分发（N 台机器同一观感）

在一台有 GPU 的机器上运行 nvtop → F2 调整（关颜色可选、刷新 0.5s、图表含功耗与 PCIe 吞吐、进程按显存降序）→ F12 保存 → 分发：

scp /root/.config/nvtop/interface.ini admin@gpu-node02:/home/admin/.config/nvtop/interface.ini

说明：目标机用户为 admin（登录密码遵循内部统一测试口令 q1w2e3r4），分发前确认目标机 ~/.config/nvtop/ 目录存在（nvtop 也会在 F12 时自动建，scp 需手动先建）。

十、常见问题（FAQ）

Q1：为什么找不到 /etc/nvtop.conf 或类似全局配置？ nvtop 没有"系统级配置文件"这一层——它是单用户交互 TUI，配置仅两处：命令行参数（临时）与每用户的 XDG interface.ini（持久）。系统级统一行为用 shell alias/脚本包装实现（见场景三）。

Q2：-c 指定的配置文件为什么没被创建？ 配置文件由 F12 触发保存时写入；无 GPU 的机器上 nvtop 在界面初始化前就退出（实测输出 No GPU to monitor.），因此不会生成文件。首次生成必须在有 GPU 的机器上按 F12。

Q3：改了 UpdateInterval 但感觉没变？ 单位是毫秒（源码 %d 直接赋给 update_interval），且命令行 -d 的单位是 0.1 秒——-d 10 等价 ini 里 UpdateInterval=1000。两处混用容易换算错，建议固定用一种入口。

Q4：-p 之后图表区还在吗？ 不在。3.3.2 的 -p 会清空每卡绘制项（源码 to_draw = 0），界面只剩设备条与进程列表；man 页"只显示一个最大值图表"是旧版描述，以 -h 实测文本与源码为准。

Q5：编译后 -i 信息栏没有时钟数据？ 该栏的扩展时钟域依赖驱动附带的 libnvidia-api.so.1（官方 README：recent drivers install alongside NVML）；库缺失时"the rest of the interface is unaffected and the bar takes no room"，属预期降级而非故障。

Q6：手编 interface.ini 为什么有些键不生效？ 键名与取值是硬编码白名单（第七节的两个值域表），非法键被静默忽略。分发预置文件时从"已调好的真机导出"，不要手写。

十一、参考链接