User Manual

1.1 · What ngtop is

ngtop is a system monitor for the terminal. It joins in one program what btop shows about the CPU, the memory and the processes, what nvtop shows about the graphics card, and what the Windows Task Manager shows about the network, the disks and the services.

It is one file. You copy it to a Linux machine and run it. There is nothing to install, no library to add and no daemon to start. It works on any distribution for the 64-bit PC (x86_64), old or new.

ngtop is light on purpose. It uses about 1% of one CPU core at the default refresh interval, so the monitor is not the busiest process on the machine it watches.

1.2 · The five sections

The interface has five sections. You switch between them with the keys 1 to 5 or with Tab, or by clicking the tab bar at the top of the screen.

1.3 · What ngtop does not do

Before you start, it helps to know what ngtop is not.

• It runs on Linux x86_64 only. There is no version for other systems or other processors.
• It shows the present, with a short history in the graphs. It does not record data over days.
• It watches the machine it runs on. To watch a remote machine, run ngtop there (for example over SSH: 2.5 “Running over SSH”).
• AMD and Intel graphics cards are read in full. NVIDIA cards are only detected and listed: full support is planned.
• The Services section needs systemd. Without it the section says so and the rest of ngtop works as usual.
• Some numbers need administrator rights. Where ngtop is not allowed to read something it shows —, never a wrong number (10.2 “What you see without administrator rights”).

1.4 · Conventions of this manual

The text of this manual uses a few simple conventions.

Examples labelled Console show a session at the shell prompt. The prompt is $; what comes after it is what you type, and the lines below are the answer.

$ ngtop --version
ngtop 1.0.0
Licence: PolyForm Noncommercial 1.0.0 — free for noncommercial use

The pictures of ngtop in this manual are real screens of the program, taken on a demonstration machine with sample data. On your computer the numbers and the names are of course different.

2.1 · Requirements

ngtop asks very little of the machine and of the terminal.

2.2 · Getting the file

ngtop is a single file named ngtop.

Download it from the project site, https://ngtop.nicfio.it. If you prefer to build it yourself you need Rust (installed with rustup) with the x86_64-unknown-linux-musl target; then, in the folder of the sources:

$ sh build.sh
$ ls -l dist/ngtop

build.sh produces dist/ngtop and checks that the file is really static, that is, that it needs no library. The technical manual describes the build in detail.

A downloaded file is not yet executable. Make it so, once:

$ chmod +x ngtop

You can leave the file where it is and start it as ./ngtop, or copy it to a folder that is in your PATH to start it just as ngtop. For example, for yourself only:

$ mkdir -p ~/.local/bin
$ cp ngtop ~/.local/bin/

2.3 · First run

Open a terminal window and run the program:

$ ngtop

The screen fills with the Overview. The numbers appear within a fraction of a second; the first CPU percentages are measured over a short first interval, then they follow the refresh interval (one second by default).

Try these first steps. None of them changes anything.

1. Press 2 to see the GPU, 3 for the processes, 4 for network and disks, 5 for the services, and 1 to come back.
2. Press F1. A window lists all the keys. Close it with Esc.
3. In the Overview, press ↓ a few times to select a process, then F6 to change the column used for sorting.
4. Press / and type a few letters of a program name: the list shows only the matching processes. Press Esc to clear the filter.
5. Press q to leave.

2.4 · Leaving ngtop

Three ways to leave ngtop: q, F10 and Ctrl+C. On exit ngtop gives the terminal back exactly as it was: the screen, the cursor and the mouse. This also happens if ngtop is stopped by a signal (such as the closing of the terminal window) or if it meets an error.

A confirmation window (for a signal or for a service action) takes the keys first. In that case Esc closes the window, and then q leaves the program.

2.5 · Running over SSH

ngtop is a good tool for a server you reach over SSH: it is a single file, so you can copy it there.

$ scp ngtop user@server:
$ ssh user@server
$ chmod +x ngtop
$ ./ngtop

If you give the program as a command, ask SSH for a terminal with -t:

$ ssh -t user@server ./ngtop

Without -t there is no terminal, and ngtop says so instead of drawing garbage:

$ ssh user@server ./ngtop
ngtop: an interactive terminal is required (run it from a terminal window). For a text summary use: ngtop --dump

• Colours. SSH often does not pass the COLORTERM variable, so ngtop falls back to 256 colours. That looks fine. If your terminal has truecolor and you want it, set colors = "truecolor" in the configuration file on the server (9.2 “The configuration file”).
• Slow links. Press + to refresh less often: each press lengthens the interval, up to 5 seconds.
• Inside tmux or screen ngtop works as in any terminal. If the colours look flat, try ngtop --256.

2.6 · A text summary with --dump

Sometimes there is no terminal at all: a script, a log, a bug report. Then use --dump. It prints a short text summary and exits, without drawing the interface.

$ ngtop --dump
CPU: AMD Ryzen 9 7900X 12-Core Processor (24 logical, 12 physical)
  total  18.2%
  core  0   22.0%  4710 MHz
  core  1   14.3%  4650 MHz
  ...
Memory: total 31.20 GiB used 9.84 GiB available 21.36 GiB cache 11.02 GiB buffers 0.31 GiB free 9.10 GiB
Swap: total 8.00 GiB used 0.00 GiB free 8.00 GiB
Load: 0.52 0.61 0.58  processes 2/611
Uptime: 4d 11:20:07
    PID USER         CPU%        MEM COMMAND
   2210 alice         6.1   0.42 GiB /usr/lib/firefox/firefox
   1534 alice         3.4   0.21 GiB /usr/bin/gnome-shell
    ...

The summary has the CPU with one line for each core, the memory and the swap, the load, the uptime, and the 15 processes that use the most CPU. It is also the quickest way to check that ngtop works on a new machine.

3.1 · The parts of the screen

Every screen of ngtop has the same three parts, from top to bottom.

3.2 · The tab bar

The tab bar is the first line. On the left are the five sections; the one you are in is highlighted. Click a tab, or press 1 to 5, or use Tab and Shift+Tab to go to the next and the previous section.

On the right, ngtop shows five facts, separated by │:

myhost │ up 3d 06:09 │ load 0.77 1.16 1.04 │ every 1s │ 13:40:04

On a narrow terminal the right side is cut first; the tabs always stay.

3.3 · Panels, meters and graphs

Each panel is a frame with a title on the top left and, often, a short piece of information on the top right: the name of the CPU, the interface, how many processes there are. The lower border sometimes carries a note, such as the scale of a graph.

Numbers are drawn in three ways.

Colours follow the value. The usual gradient goes from green (low) through yellow to red (high). CPU, memory, network and disks each have their own hue, so you can tell the panels apart at a glance.

3.4 · The key bar and the status line

The last line of the screen is the key bar. It shows the main keys of the section you are in, each with its action. It changes when you change section. While you type a filter it shows Enter (Confirm) and Esc (Cancel and clear).

When something happens, the result replaces the key bar for about five seconds: in green if it went well, in red if it failed. This is the status line. Examples:

SIGTERM sent to 4121 firefox
nice of 4121 firefox (main thread): 0 → 1
configuration saved to /home/alice/.config/ngtop/config.toml
SIGTERM to 4121 firefox: permission denied (EPERM)

The Services section writes its results on the lower border of the list instead (8.7 “Starting and stopping”).

The key bar is a reminder, not the full list. The full list is in the help window (3.7 “The help window”) and in the chapter ch. 12 “Key reference”.

3.5 · Keyboard

Everything in ngtop can be done with the keyboard. The mouse is a convenience.

Every section adds its own keys, listed in its chapter and, all together, in the chapter ch. 12 “Key reference”. Letters are case-sensitive: W saves the configuration, w does nothing.

3.6 · Mouse

If your terminal reports the mouse, ngtop uses it.

To turn the mouse off, start with --no-mouse or set mouse = false in the configuration file. Then your terminal handles the mouse itself, and you can select and copy text on the screen as usual.

3.7 · The help window

Press F1 in any section. A window lists the keys that work everywhere and the keys of each section.

Close it with Esc, Enter, F1 or q. While the window is open the other keys do nothing, and the screen behind it keeps updating.

3.8 · The compact layout

ngtop adapts to the size of the terminal. With 100 columns or more and 30 rows or more it uses the full layout. Below that, it switches by itself to the compact layout, and returns to the full one when you enlarge the window.

In the compact layout the Overview becomes a column of single lines (CPU, memory, GPU, network, disks) above the process list. The key bar is shorter too: Filter is on / and Sig stands for the signal. The other sections squeeze their panels, and hide the columns that do not fit.

3.9 · Colours

ngtop uses the best colours your terminal can show and chooses by itself:

If the choice is wrong for your terminal, force it: --256 on the command line, or colors = "truecolor" or colors = "256" in the configuration file (9.2 “The configuration file”). 11.2 “Colours look wrong” has the symptoms and the cures.

3.10 · The refresh interval

ngtop reads the system once for each refresh interval. The default is one second. The interval is always shown in the tab bar (every 1s).

Press + to make the interval longer and - to make it shorter. It moves on five steps:

The change takes effect at once. It is lost when you quit, unless you press W, which saves it with the current section. To start with another interval, use --delay (9.1 “Command-line options”).

4.1 · The Overview at a glance

The Overview is the first screen. It puts the whole machine on one page: how busy the CPU is, where the memory went, what the graphics card and the network are doing, how full the disks are, and which processes use the most.

The screen has two columns. The left column holds the small panels and the right column the process list. The CPU panel runs across the top. The left column takes 40% of the width by default; 4.7 “Changing the width of the left column” tells how to change it.

4.2 · CPU

The cpu panel has the name of the processor and the number of threads in its title.

• The first line is the total: CPU, a meter, the percentage, the temperature of the processor and the average clock speed (for example 14% 42°C 0.92GHz).
• Under it come the cores: C0, C1 and so on, each with its own meter and percentage. A hyper-threaded core counts as two threads, so a 12-core processor shows 24 meters.
• The big graph on the left is the history of the total use. Newest is on the right.
• If the panel is too low to show all the cores, the lower border says +N cores not shown. Make the terminal taller to see them.

A value of 100% means every thread is fully busy. The temperature comes from the sensors of the kernel; if the machine has none that ngtop can use, it is simply not shown.

4.3 · Memory

The mem panel has the total memory in its title, and one line for each kind.

Each line has a meter and a small history. Below the lines, when they exist, ngtop adds one line of notes: ZRAM (compressed memory used as swap, with the compression ratio), zswap (the compressed swap cache) and Dirty (data waiting to be written to disk).

4.4 · GPU and network panels

Two small panels sit under the memory.

• gpu0 is a card of the first graphics card: its name in the title, then GPU (use), MEM (graphics memory), VID (video engine) and the clock, as far as the card reports them. If you have more than one card, press d to show the next one. All the details are in the chapter ch. 5 “GPU”. If the card is asleep, the panel says so instead of waking it.
• net shows one network interface: the name and the IP address in the title, then the download (▼) and upload (▲) speeds, the highest speed seen since ngtop started (peak) and the total transferred (total). The graph has a scale, written on the lower border (scale 128KB/s), that adapts to the traffic. If there is more than one interface, the title shows ‹ › and n and N switch to the next and the previous one. ngtop starts with the interface that has the default route. An interface that is down is marked (down).

The chapter ch. 7 “Network & Disks” shows the same data in more depth, with the connections.

4.5 · Disks panel

The disks panel shows, in its title, the total reading and writing speed of all physical disks (R 0.0 W 0.0 MB/s). Then there is one line for each mounted file system: where it is mounted, a meter of how full it is, the used and total sizes, and a small history of the disk activity.

If there are more file systems than lines, the lower border says +N more. The chapter ch. 7 “Network & Disks” lists them all.

4.6 · The process panel

The processes panel is a smaller version of the ch. 6 “Processes” section.

• The title shows the filter you typed, the column used for sorting (‹ cpu ›) and whether the view is a list or a tree.
• The lower border counts the processes and threads of the whole machine and the position of the selection (247 processes · 822 threads · sel. 1/247).
• The columns are PID, Name, Command, User, Thr (threads), Mem and CPU%. If the machine has a GPU in use, two columns GPU% and VRAM are added. A narrow panel hides the columns that do not fit.
• The percentage is a share of the whole machine: 100 means every core is busy. A process that fills one core of eight shows 12.5.

Sorting starts on CPU, highest first. Press F6 (or >) to move to the next column, < to go back, i to reverse the order, or click a column header. The columns in the cycle are PID, name, user, memory, CPU, GPU and VRAM. Memory, CPU, GPU and VRAM start with the highest value on top; the others start in alphabetical or numerical order.

Press F5 to change between the flat list and the tree, where every process is shown under its parent. / opens the filter box (the chapter ch. 6 “Processes” explains it). F9 opens the window to send a signal to the selected process. To see the details of a process, or to fold branches of the tree, go to the Processes section: 3.

4.7 · Changing the width of the left column

The left column takes 40% of the width. To change it, put a line in the configuration file:

left_width = 50

The value is a percentage between 20 and 70. There is no key and no command-line option for it. See 9.2 “The configuration file”.

4.8 · Keys of the Overview

These are the keys of the Overview, as the program reports them.

The keys that work everywhere (sections, help, interval, save, quit) are in ch. 12 “Key reference”.

5.1 · What the GPU section shows

The GPU section is ngtop's answer to nvtop. It shows every graphics card of the machine, how busy each one is, and which processes use it.

From top to bottom the screen has the panels of the cards, the history of the selected card with its engines and its power, and the table of the processes that use the GPU.

5.2 · Supported cards

ngtop reads the graphics cards from the kernel, not from a vendor program. What it can show depends on the driver.

If ngtop finds no card at all, the section says No GPU detected.

5.3 · The panel of a card

Each card has a panel. The title says GPU 0 · Name of the card; on the right it gives the kind, the memory size, the driver and the PCI address, for example integrated · i915 · 0000:00:02.0.

Inside, ngtop shows the values the card reports, two to a line. Only what exists is shown.

5.4 · Integrated and discrete cards

ngtop distinguishes two kinds of card, because they behave differently.

• An integrated GPU is part of the processor (or sits on the motherboard) and shares the main memory. The title says integrated. ngtop always reads it.
• A discrete GPU is a separate card with its own memory. It can go to sleep to save power.

When a laptop or a desktop has both, you see two panels, GPU 0 and GPU 1. If they do not fit side by side they are stacked.

5.5 · Sleeping cards

A discrete card in power saving is asleep. Reading its files would wake it up, which costs power and defeats the purpose of letting it sleep. So ngtop does not read a sleeping discrete GPU. Its panel says:

As soon as some program wakes the card, ngtop shows its numbers again. In the compact layout the short word suspended is written instead.

Integrated cards are different: they switch on and off all the time while the machine works, so there is nothing to save, and ngtop reads them always. When the card is idle at that moment, the title shows idle.

5.6 · History, engines and power

Under the cards, when the window is tall enough, there are three more panels about the selected card (the first one, or the one you chose with d).

• GPU 0 history: a graph of use, memory and temperature over time (use · VRAM · temp), with a scale 0, 50 and 100%.
• engines · GPU 0: the use of each engine of the card, as meters. The names are: 3D / gfx, Compute, Copy (DMA), Video, Video enh., Encode, Decode. If the processes cannot be read the panel says no data (clients not readable).
• power: a graph of the watts. It says not available when the driver does not report power.

The engines panel and the power panel appear only if the window is at least 100 columns wide.

5.7 · Processes using the GPU

The bottom of the section is the table GPU processes: only the processes that are using a graphics card. Its title shows the sort column, the number of processes and the sum of their graphics memory.

The table works like the process list. ↑ and ↓ select, F6 changes the sort column (the list includes GPU and VRAM), / filters, and F9 sends a signal to the selected process (6.7 “Sending a signal”).

5.8 · Switching the card

With more than one card, press d to select the next one. The marker ● in the title shows the selected card. The history, engines and power panels follow the selection. So does the gpu0 panel of the Overview.

The process table lists the processes of all cards together; the DEV column tells which card each process uses.

5.9 · Keys of the GPU section

The keys of the GPU section, as the program reports them.

6.1 · The Processes screen

The Processes section shows every process of the machine and, for the one you select, a panel of details. It is the place to find out what is slow, what is eating memory, and to stop what should not be running.

On the left there is the table of the processes. On the right there are three panels about the selected process: the details (with tabs), its CPU history, and its memory and input/output. The selection stays on the same process when the order of the list changes, because ngtop follows the PID, not the row.

6.2 · Tree and list

The table has two views, which you switch with F5.

The columns are PID, User, CPU%, Mem, GPU% and Name. On a narrow panel the user and GPU columns are hidden first. Mem is the resident memory (the part of the process that is in RAM now). CPU% is a share of the whole machine (0–100); the CPU panel of the detail shows the same process as % of one core.

The lower border counts everything: 251 processes · 828 threads · sel. 1/251 means 251 processes, 828 threads in total, and the first of 251 rows is selected.

6.3 · Folding branches

In the tree, a process that has children shows ▾ when its branch is open and ▸ when it is folded. Press Space on a process to fold or open its branch. A folded branch hides all the descendants. The top border reminds you: ▸ closed ▾ open · Space folds.

6.4 · Filtering

To look for a process, press /. A text box opens in the title of the table: filter: _. Type a few letters. The list shrinks at every letter.

The filter looks, without regard to upper and lower case, in the name, the whole command line, the user and the PID. So fire finds Firefox, alice finds her processes and 4121 finds that PID.

The filter works in the Overview and in the GPU section too, and it is the same filter: if you leave it on, it is still there when you change section.

6.5 · Sorting

In the list view, and in the tree too, you can sort by a column.

• F6 or >: next column. <: previous column. The cycle is PID, name, user, memory, CPU, GPU, VRAM.
• i: reverse the order of the current column.
• Click a column header: sort by it. Click again to reverse.
• The arrow in the header (CPU%▼) shows the column and the direction.

When you pick memory, CPU, GPU or VRAM, the biggest value goes on top. The other columns start from the smallest.

6.6 · The detail panel

The right side shows the process that is selected. The title of the first panel is the name of the process and its PID, and on the right the owner. A row of tabs gives seven views. Change tab with ← and →, or click it. If a tab has more lines than fit, scroll with [ and ] or with the mouse wheel over the panel.

Only the tab you look at is read. When you change tab, the panel says reading… for an instant. This keeps ngtop light, even for a process with thousands of open files.

Under the tabs there are two more panels.

• CPU: the history of the CPU use of this process, and on the right its current value in % of one core.
• memory & I/O: RSS (resident memory), PSS (the fair share of memory when pages are shared), Shared, Swap, VRAM (graphics memory), and the reading and writing totals (Read, Write) and speeds (R/s, W/s).

6.7 · Sending a signal

A signal is a message that the system delivers to a process. The common use is to ask a program to quit, or, when it is stuck, to stop it. To send one:

1. Select the process in the table (or in the Overview, or in the GPU table).
2. Press F9 (in Processes also k). The window Send signal opens.
3. Choose the signal with ↑ and ↓. The first one, SIGTERM, is the polite request and is already selected.
4. Optionally press Space to send the signal to the whole subtree: the process and all its children.
5. Press Enter to send, or Esc to cancel.

The result appears on the status line at the bottom: SIGTERM sent to 4121 firefox in green, or the reason of the failure in red.

6.8 · What ngtop protects you from

A signal acts on the real system, and a mistake can be costly. ngtop adds several protections, so that you cannot hit the wrong target by accident.

6.9 · Changing the priority

Every process has a nice value from −20 to 19. The higher the number, the more "polite" the process is, and the less CPU it gets when the machine is busy. The default is 0.

• F8: nice +1 on the selected process (less priority).
• F7: nice −1 (more priority).

Like htop, ngtop changes the main thread of the process. The status line says what happened: nice of 4121 firefox (main thread): 0 → 1.

Any user can raise the nice value of their own processes. To lower it (give more priority) you need root, and ngtop says root is needed to lower the nice value. At the limits the message is already at the limit.

The current nice and the priority are in the General tab, on the line Priority.

6.10 · Keys of the Processes section

The keys of the Processes section, as the program reports them.

7.1 · The Network & Disks screen

This section answers three questions: how much is the network carrying, who is talking, and how are the disks doing.

When the terminal is not tall enough for everything, ngtop keeps the network first, then the connections, the interfaces, the disks and the file systems.

7.2 · Interfaces

The panel interface is named after the selected interface, for example interface eth0, with its addresses on the right. Inside you see the graphs of the two directions and these numbers:

The lower border shows the scale of the graph (scale 128KB/s), which follows the traffic, and the reminder i: switch. Press i to go to the next interface, I for the previous one, or click one in the list. ngtop starts with the interface of the default route.

The panel interfaces lists them all: Name, IPv4 address, the speeds ▼ and ▲, and the State (● up or ○ down). Below there is a line with the DNS server and the gateway: DNS 9.9.9.9 · gateway 192.168.1.1.

7.3 · Connections

The panel connections lists the TCP and UDP sockets of the machine. This is where you find out which program is talking to which address.

The title on the right shows the current filters and the count, for example TCP+UDP · LISTEN yes · 170 · sort state. These keys change what you see:

If nothing matches, the table says no connections match these filters. ngtop reads the connections only while this section is on the screen, so the other sections stay lighter.

7.4 · From a connection to its process

You see a connection and want to know more about the program behind it? Select it and press Enter. ngtop jumps to the Processes section with that process selected, opening the folded branches that hide it, and clearing the filter if it would hide it.

• If the connection has no process (—), nothing happens.
• If the process ended in the meantime, the status line says process N has exited.
• F9 instead opens the signal window for that process without leaving the section. This is the quick way to stop a program that is flooding the network (6.7 “Sending a signal”).

7.5 · Disks

Under the connections there is one panel for each physical disk, named after the device (sda, nvme0n1). Partitions, loop devices, RAM disks and device-mapper volumes are not listed: they would only repeat what the real disk shows.

With many disks, the panel shows a page at a time and the border says 1-3 of 8 · PgUp/PgDn. Turn the page with PgUp and PgDn.

7.6 · File systems

The panel filesystems lists what is mounted, one line each.

Only real file systems are listed: the ones kept on a disk or on the network (ext2/3/4, btrfs, xfs, f2fs, vfat, exfat, zfs, ntfs, nfs, cifs and a few more). System ones such as tmpfs or proc, and the storage of containers and snap packages, are left out. A column that does not fit the width is dropped.

7.7 · A mount that does not respond

A network disk (NFS, CIFS) can stop answering: the server is off, the network is down. Programs that touch it freeze. A monitor must not freeze with them.

ngtop asks each file system for its free space from a separate thread. If one does not answer within 5 seconds, the line stays in the table with not responding in red in the Use column, and the rest of the screen goes on working. When the mount answers again, the numbers return.

7.8 · Resetting peaks and totals

Peaks and totals grow as time passes. To start counting from now, press z: it resets the peaks and sets the totals to zero for all interfaces. Nothing else is changed. This is useful to measure one download: press z, start the download, and read total at the end.

7.9 · Keys of the Network & Disks section

The keys of the Network & Disks section, as the program reports them.

8.1 · The Services screen

The Services section is a window on systemd, the program that starts and supervises the services of most Linux distributions. It lists the units, shows what each one is doing and what it wrote in the journal, and lets you start, stop and restart it.

On a wide terminal (100 columns or more) the list of units is on the left and the details of the selected unit on the right. On a narrow terminal the details go under the list. On a large one (at least 120 columns by 38 rows) two more panels appear at the bottom: the boot time and the users with their sessions.

8.2 · The list of units

The list shows one unit on each line.

The state has a symbol and a colour:

8.3 · Filters and search

A real system has hundreds of units. Along the top of the list there are six filters, each with the number of units it matches:

All 280  Active 176  Failed 0  Enabled 37  Timers 8  Sockets 19

• f goes to the next filter: All, Active, Failed, Enabled, Timers, Sockets. The chosen one is highlighted.
• / opens a search box in the title of the list. It looks in the name and in the description, ignoring case. Enter keeps the search, Esc clears it. The search and the filter work together: you can look for ssh among the Active units only.
• A quick way to see what is wrong: press f until Failed is highlighted.

8.4 · System and user units

There are two worlds of units. At the right end of the filter line you see ‹ system │ user ›. Press u to switch.

• system: the units of the machine, started at boot and run as root: the web server, the network, the clock.
• user: the units of your login, started by your own systemd instance: the sound server, a sync tool, a timer you wrote. They need no password.

When you switch, the list is read again from the other side.

8.5 · The detail of a unit

The panel on the right is named after the selected unit. It shows:

Below these lines is the end of the unit's journal, the log that systemd keeps. Its heading is journal (journalctl -u NAME), or --user-unit for a user unit. It is read again every five seconds.

When the detail panel is too small for all the lines, the least important ones are dropped first.

8.6 · The journal

To read the journal at length, press j. The journal of the selected unit takes the whole screen, titled journal · NAME. Press j or Esc to go back.

8.7 · Starting and stopping

Four keys act on the selected unit:

Nothing happens at once. A window asks for confirmation:

The window shows the unit, the scope (system or user) and a reminder that the system may ask for a password. Two buttons: Cancel and Confirm. Cancel is selected, so pressing Enter by habit does nothing. Move to Confirm with ← → or Tab, then Enter. Esc or n cancel.

The result is written on the lower border of the list: Restart requested: cron.service, Enabled: NAME or the error in red. The list and the detail are read again immediately, so you see the new state. Only one action is handled at a time.

8.8 · Passwords, polkit and sudo

ngtop does not ask for passwords and does not keep any. When you act on a system unit, ngtop asks systemd, and systemd asks polkit whether you are allowed. What happens next depends on where you are.

So on a server, the practical way is to start ngtop with sudo when you need to act on services, and without it for just looking:

$ sudo ngtop --section 5

8.9 · Boot time

On a large terminal the bottom left panel is boot. Its title says when the machine last started and how long the start took: last boot: 2026-10-20 07:30 · 19.4 s.

• A bar split into the phases of the start: firmware, loader, kernel, initrd and services, each with its seconds. Phases that do not exist on the machine are left out.
• Under the bar, slowest (systemd-analyze blame): the units that took longest to start, with a bar and their time.

This is the first place to look when a machine seems to start slowly. If the data are not available (in a container, or if the start has not finished), the panel says boot times unavailable (container?).

8.10 · Users and sessions

The bottom right panel is users & sessions: who is logged in and what they use.

Users that have no session but run processes (the system accounts) follow, ordered by memory.

8.11 · When systemd is not there

The section needs systemd. On a machine that uses something else (OpenRC, runit, a minimal container), the section shows one line: Services unavailable: systemd not found. The other four sections are not affected.

8.12 · Keys of the Services section

The keys of the Services section, as the program reports them.

9.1 · Command-line options

You can start ngtop with options that change how it starts. They are all optional.

An option with a value can be written with a space or with =: --delay 500 and --delay=500 are the same. The short forms -d and -s take the value after a space.

Examples:

$ ngtop -d 500 -s 3        # refresh every 500 ms, start on Processes
$ ngtop --no-mouse        # leave the mouse to the terminal
$ ngtop --256             # force 256 colours
$ ngtop --config myconfig
$ ngtop --dump            # print a text summary and exit

• The interval of --delay is between 250 and 5000 ms. A value in between is rounded to the nearest of the five steps (250, 500, 1000, 2000, 5000).
• A wrong option or value prints a message and Try 'ngtop --help'., and ngtop exits with code 2 without opening the screen.
• --help and --version print and exit; they work without a terminal.

9.2 · The configuration file

ngtop can remember your preferences in a small text file. You do not need one: without it, ngtop uses the defaults.

The file is config.toml in the folder ngtop of your configuration folder:

To use another file, start with --config FILE. That file must exist; the default one may be missing.

The format is simple: one setting on each line, written name = value. Text values go in double quotes, numbers are plain, and yes/no values are true or false. Everything after a # is a comment. Empty lines are ignored.

# ngtop configuration
# refresh interval in ms (250–5000)
interval = 1000
# start section: 1 Overview, 2 GPU, 3 Processes, 4 Network & Disks, 5 Services
section = 1
# mouse enabled
mouse = true
# colors: "auto", "truecolor" or "256"
colors = "auto"
# temperature unit: "C" or "F"
temperature = "C"
# width of the left column of the Overview, in % (20–70)
left_width = 40

9.3 · Every setting

These are all the settings. A missing line means the default.

9.4 · Which setting wins

Three places can say the same thing. ngtop uses them in this order, from the strongest:

• the command line (--delay, --section, --no-mouse, --256),
• the configuration file,
• the defaults of the program.

So ngtop -d 250 beats a file with interval = 2000. The interval can also be changed while ngtop runs, with + and -.

9.5 · Saving with W

You do not have to edit the file. Arrange ngtop as you like (the interval with + and -, the section you want to start on) and press W (capital). ngtop writes the current interval and the current section to the file and says so on the status line:

configuration saved to /home/alice/.config/ngtop/config.toml

• If the file does not exist, ngtop creates it, with the folder if needed, with all the settings and the comments shown above.
• If it exists, ngtop changes only the two lines interval and section. Your comments, the order and the other settings are left as they are. If a line was missing, it is added at the end.
• The write is safe: ngtop writes a temporary file and then renames it, so a failure never leaves a half-written configuration.
• The other settings (mouse, colours, temperature, width) are never changed by W: edit them by hand.

If something goes wrong the status line says why, in red: configuration not saved (PATH): …, or no configuration path (HOME is not set) when ngtop has no folder to use.

9.6 · Mistakes in the file

ngtop reads the file at start-up. If it finds a mistake it does not guess: it prints a message with the line number and exits with code 2, before changing the screen.

$ ngtop
ngtop: configuration /home/alice/.config/ngtop/config.toml: line 3: 'interval' must be between 250 and 5000 (found 10)

A setting ngtop does not know is not an error. It is reported and ignored, and ngtop starts normally:

ngtop: configuration /home/alice/.config/ngtop/config.toml: warning, line 7: unknown key 'colour', ignored

Exit codes of ngtop: 0 normal; 2 a wrong option, a wrong configuration file, or no interactive terminal; 1 a terminal error while running.

10.1 · What a normal user can see

ngtop is made to work for a normal user. It reads the information that the kernel publishes for everybody (/proc and /sys) and needs no special rights for it. You get the CPU, memory, load, network speeds, disks, file systems, the list of all processes with their CPU and memory, and the services.

A few details are private to their owner, or to root. When ngtop is not allowed to read a value it shows a dash, —, and goes on. It never shows a made-up number, and it never stops.

10.2 · What you see without administrator rights

This is where you meet a dash as a normal user, and the reason.

What you do see for every process, whoever owns it: the PID, the name, the command line, the user, the number of threads, the resident memory, the CPU, the state, the nice value and the open network sockets of the whole machine. And everything about your own processes.

10.3 · What a normal user can do

Viewing and acting are different. As a normal user you can:

• send signals to your own processes; for the others the system says permission denied (EPERM);
• raise the nice value of your own processes (F8); lowering it needs root: root is needed to lower the nice value;
• act on user units without a password; on system units, only if the system authorises you.

See 6.8 “What ngtop protects you from” for the checks that ngtop adds on top of the permissions of the system.

10.4 · Running as root

To see everything, run ngtop as root:

$ sudo ngtop

Now the dashes of the table above turn into numbers, the services can be started and stopped without questions, and every process can receive a signal.

• With sudo, the configuration file may be a different one: depending on how sudo is set up, root may use its own home folder. To be sure which file is used, add --config FILE.
• You do not need root just to look at the Overview, the Network or the processes of your own user.
• Some systems mount /proc so that users see only their own processes. On those, a normal user sees an almost empty list, and root sees everything.

10.5 · What ngtop does on your system

Is it safe to leave ngtop open as root? ngtop only reads files and, when you ask, sends a signal, changes a nice value, or asks systemd for an action. It does not open network ports, does not write anything outside the configuration file (only with W), and does not run other programs, except journalctl and systemd-analyze to read the journal and the boot times.

11.1 · The terminal is too small

The screen is empty, or crowded.

• Below 100 columns or 30 rows ngtop uses the compact layout (3.8 “The compact layout”). Enlarge the window to get the full one.
• Below 10 columns or 4 rows nothing can be drawn. Enlarge the window.
• On a narrow window some columns and the right part of the tab bar disappear. That is normal: they come back with the space.

ngtop follows the resizing of the window at once; there is nothing to restart.

11.2 · Colours look wrong

No colours, flat colours, or wrong colours. ngtop decides by looking at two variables of the environment, COLORTERM and TERM (3.9 “Colours”). When that is wrong, tell it:

11.3 · Braille characters are not shown

The graphs show boxes, question marks or gaps. The graphs are drawn with braille characters, and the frames with box-drawing characters.

• Check that the terminal uses UTF-8: locale should show a name ending in UTF-8 (for example en_US.UTF-8). If not, set it (export LANG=en_US.UTF-8).
• Choose a font that has braille. Most monospace fonts of modern systems do (DejaVu Sans Mono, Noto Sans Mono, JetBrains Mono, Fira Code…). If the graphs have holes, change the font of the terminal.
• The font of the Linux text console has only a few of these characters. Use a terminal emulator in a graphical session, or read the numbers: they are always there.

11.4 · It needs an interactive terminal

"ngtop: an interactive terminal is required". ngtop needs a real terminal for its keys and its screen. It refuses to start when its input or output is not one:

ngtop: an interactive terminal is required (run it from a terminal window). For a text summary use: ngtop --dump

• You ran it in a script, from cron, from a service, or with the output sent to a file or to a pipe (ngtop | less).
• You ran it over SSH as a command: ssh host ngtop. Add -t: ssh -t host ngtop.
• You want the numbers, not the screen: use ngtop --dump (2.6 “A text summary with --dump”).

11.5 · The GPU is not shown

The GPU is not shown, or shows no numbers.

11.6 · Services does not work

The Services section does not work.

11.7 · A disk does not respond

A file system says "not responding". It is a network disk (NFS, CIFS) that does not answer, and ngtop shows it in red after five seconds (7.7 “A mount that does not respond”). ngtop itself keeps working. Check the server and the network. A shell that enters that folder would freeze: do not.

11.8 · Keys that do nothing

A key does nothing.

• The terminal may keep some keys for itself: F1 (its own help), F10 (its menu), F11 (full screen). ngtop has other keys for most actions: q quits, / filters, < and > sort, k opens the signal window in Processes.
• A window is open (help, signal, confirmation) and takes the keys. Close it with Esc.
• You are typing in a filter box: every letter goes into it. Press Enter or Esc.
• Letters are case-sensitive: W and w are different keys.
• The key belongs to another section: the key bar shows the keys that work where you are.

11.9 · Mouse and terminal problems

The mouse does not work, or the terminal behaves oddly after ngtop.

• Some terminals do not pass the mouse. Use the keyboard, or try another terminal.
• If the mouse prevents you from selecting text, hold Shift while you drag, or start with --no-mouse.
• ngtop restores the terminal when it leaves, even after an error or a signal like the one sent when a window closes. If ngtop is killed with kill -9, nothing can restore it. The terminal may then show strange characters or echo nothing. Type reset and press Enter (even if you do not see what you type).

11.10 · Wrong time

The clock or the dates are wrong. ngtop shows the local time of the machine. It takes the time zone from the variable TZ or from /etc/localtime. If that file is missing or damaged, ngtop uses UTC. Check the time zone of the machine (timedatectl).

11.11 · High CPU use

ngtop uses too much CPU. It normally uses about 1% of one core at the default interval. A short interval (250 ms), a very big process list or a slow link cost more. Press + to refresh less often.

11.12 · Numbers that differ from other tools

The numbers differ from another tool. The definitions are different, not the data.

• The CPU% of a process is a share of the whole machine, 0–100 (top and htop count per core instead, so they show N times more on N cores).
• Used memory is the total minus the available memory; the file cache is not counted as used.
• Graphs and peaks start when ngtop starts; the totals of a network interface count since it was created, until you press z.

12.1 · Keys valid in every section

The keys that work in every section. This table and the next ones are produced by the program itself.

12.2 · Overview keys

The Overview (key 1).

12.3 · GPU keys

The GPU section (key 2).

12.4 · Processes keys

The Processes section (key 3).

12.5 · Network & Disks keys

The Network & Disks section (key 4).

12.6 · Services keys

The Services section (key 5).

12.7 · Keys inside windows and boxes

When a window or a box is open, it takes the keys. Everything else is ignored until you close it.

The tables of the sections list every key. Where the key bar shows two labels for one key (for example Search and Filter), they are two names for the same action.

13.1 · Words used in this manual

Available memory

The memory that programs can still get without swapping. It counts the free memory and the part of the cache the system would give back.

Braille characters

Unicode characters (U+2800 to U+28FF) that each hold a small grid of eight dots. ngtop uses them to draw its graphs.

Cache

Memory that holds copies of files read from disk, to make the next reading faster. It is released when programs need it.

cgroup

A control group: the way Linux gathers processes to count and limit their memory and CPU. Systemd puts every service in its own.

Compact layout

The shorter form of the screen that ngtop uses below 100 columns or 30 rows.

D3cold

The deepest power-saving state of a PCI device, with the power fully cut. A graphics card in this state is not read.

Discrete GPU

A graphics card separate from the processor, with its own memory.

Distribution

A version of Linux: Debian, Ubuntu, Fedora, Arch, openSUSE…

ESTAB

A TCP connection that is established and in use.

File system

The way data are organised on a disk: ext4, btrfs, xfs, vfat… Also what is mounted at a folder.

Inode

The entry that describes a file on a disk. A disk with no free inodes cannot take new files even when it has free space.

Integrated GPU

A graphics unit built into the processor, which shares the main memory.

IOPS

Input/output operations per second: how many reads and writes a disk does.

Journal

The log that systemd keeps for every service. ngtop reads it with journalctl.

LISTEN

A TCP socket that waits for incoming connections: a server.

Load average

The average number of processes that wanted a CPU, over the last 1, 5 and 15 minutes.

Mount

To attach a file system to a folder. A mounted file system appears in the filesystems panel.

nice

A number from −20 to 19 on a process. The higher it is, the less CPU the process gets when the machine is busy.

NVML

NVIDIA's library to read its cards. A static program cannot load it cleanly, which is why NVIDIA support in ngtop is only planned.

PID

The number that identifies a process.

pidfd

A handle to a process that stays tied to that process even if its PID is reused. ngtop uses it to send signals safely.

polkit

The part of the system that decides whether a user may do an action, and that asks for the password.

Process

A running program. A process has a PID, an owner and one or more threads.

PSS

Proportional set size: the memory of a process with the shared pages divided among the processes that share them.

RSS

Resident set size: the part of a process's memory that is in RAM now.

Signal

A short message sent to a process: for example SIGTERM, "please quit", or SIGKILL, "stop now".

Socket

One end of a network connection (or of a local connection between programs).

Subtree

A process with all its children, grandchildren and so on.

Swap

Disk space used as an extension of memory. A lot of swap in use means the machine is short of memory.

systemd

The program that starts and supervises the services in most Linux distributions.

Thread

A flow of work inside a process. A process can have many.

Truecolor

A terminal that can show 16 million colours (24 bit).

Unit

An item that systemd manages: a service, a socket, a timer, a mount…

VRAM

The memory of a graphics card.

Zombie

A process that has ended but whose parent has not yet collected its result. It uses no CPU.