bottom/README.md

bottom

A cross-platform graphical process/system monitor with a customizable interface and a multitude of features. Supports Linux, macOS, and Windows. Inspired by both gtop and gotop.

Theme based on gruvbox (see sample config). Recorded on version 0.2.0.

This documentation is relevant to version 0.3.0. Please refer to release branch or crates.io for the most up-to-date release version.

Table of Contents

• Installation

  • Manual

  • Cargo

  • AUR

  • Debian (and Debian-based)

  • Homebrew

  • Scoop

  • Chocolatey

• Usage

  • Flags

  • Options

• Keybindings

  • General
  • CPU bindings
  • Process bindings
  • Process search bindings

• Features

  • Process filtering

  • Zoom

  • Maximizing

  • Config files

    • Config flags

    • Theming

    • Layout

  • Compatibility

• Contributors

• Thanks

Installation

Note that binaries are built on the stable version of Rust, and I mainly test and release for 64-bit.

Manual

Clone from this repo or from Releases, and build with cargo build --release.

Cargo

cargo install bottom

AUR

yay bottom

# If you instead want the binary version:
yay bottom-bin

Debian

A .deb file is provided on each release:

curl -LO https://github.com/ClementTsang/bottom/releases/download/0.2.2/bottom_0.2.2_amd64.deb
sudo dpkg -i bottom_0.2.2_amd64.deb

Homebrew

brew tap clementtsang/bottom
brew install bottom

# If you need to be more specific, use:
brew install clementtsang/bottom/bottom

Scoop

scoop install bottom

Chocolatey

choco install bottom

# Version number may be required for newer releases:
choco install bottom --version=0.2.2

Usage

Run using btm.

Flags

-h, --help                      Prints help information, including flags and options
-a, --avg_cpu                   Shows the average CPU usage in addition to per-core
-m, --dot-marker                Uses a dot marker instead of the default braille marker
-c, --celsius                   Displays the temperature type in Celsius [default]
-f, --fahrenheit                Displays the temperature type in Fahrenheit
-k, --kelvin                    Displays the temperature type in Kelvin
-l, --left_legend               Displays the CPU legend to the left rather than the right
-u, --current_usage             Sets process CPU usage to be based on current total CPU usage
-g, --group                     Groups together processes with the same name by default
-S, --case_sensitive            Search defaults to matching cases
-W, --whole                     Search defaults to searching for the whole word
-R, --regex                     Search defaults to using regex
-s, --show_disabled_data        Shows disabled CPU entries in the CPU legend
-b, --basic                     Enables basic mode, removing charts and condensing data

Options

-r, --rate <MS>                 Set the refresh rate in milliseconds [default: 1000]
-C, --config <PATH>             Use the specified config file; if it does not exist it is automatically created
-t, --default_time_value <MS>   Sets the default time interval for charts in milliseconds [default: 60000]
-d, --time_delta <MS>           Sets the default amount each zoom in/out action changes by in milliseconds [default: 15000]

Keybindings

General

q, Ctrl-c	Quit bottom
Esc	Close dialog windows, search, widgets, or exit maximized mode
Ctrl-r	Reset display and any collected data
f	Freeze/unfreeze updating with new data
Ctrl-arrow key Shift-arrow key H/J/K/L	Move to a different widget (on macOS some keybindings may conflict)
Up,k	Scroll up in tables
Down, j	Scroll down in tables
?	Open help menu
gg, Home	Jump to the first entry of a table
Shift-g, End	Jump to the last entry of a table
Enter	Maximize widget
+	Zoom in on a chart
-	Zoom out on a chart
=	Reset zoom
Mouse scroll	Table: Scrolls through the list Chart: Zooms in or out by scrolling up or down respectively

CPU bindings

/	Open filtering for showing certain CPU cores
Space	Toggle enabled/disabled cores
Esc	Exit filtering mode

Processes bindings

dd	Kill the selected process
c	Sort by CPU usage, press again to reverse sorting order
m	Sort by memory usage, press again to reverse sorting order
p	Sort by PID name, press again to reverse sorting order
n	Sort by process name, press again to reverse sorting order
Tab	Group/un-group processes with the same name
Ctrl-f, /	Open process search widget

Process search bindings

Tab	Toggle between searching by PID or name
Esc	Close the search widget (retains the filter)
Ctrl-a	Skip to the start of the search query
Ctrl-e	Skip to the end of the search query
Alt-c/F1	Toggle matching case
Alt-w/F2	Toggle matching the entire word
Alt-r/F3	Toggle using regex

Features

As yet another process/system visualization and management application, bottom supports the typical features:

• CPU, memory, and network usage visualization

• Display information about disk capacity and I/O per second

• Display temperatures from sensors

• Process management (process killing is all you need, right?)

It also aims to be:

• Lightweight

• Cross-platform - supports Linux, Windows, and macOS

In addition to these things, bottom also currently has the following features:

Process filtering

On any process widget, hit / to bring up a search bar. If your layout has multiple process widgets, note this search is independent of other widgets. Searching supports regex, matching case, and matching entire words. Use Tab to toggle between searching by PID and by process name.

Zoom

Using the +/- keys or the scroll wheel will move adjust the current time intervals of the currently selected widget. Widgets can hold different time intervals independently.

Maximizing

Only care about the CPU widget right now? Then go to the widget and hit Enter to make it take up the entire drawing area.

Config files

bottom supports reading from a config file to customize its behaviour and look. By default, bottom will look at ~/.config/bottom/bottom.toml or C:\Users\<USER>\AppData\Roaming\bottom\bottom.toml on Unix and Windows systems respectively.

Note that if a config file does not exist at either the default location or the passed in location via -C or --config, one is automatically created with no settings applied.

Config flags

The following options can be set under [flags] to achieve the same effect as passing in a flag on runtime. Note that if a flag is given, it will override the config file.

These are the following supported flag config values:

Field	Type
avg_cpu	Boolean
dot_marker	Boolean
left_legend	Boolean
current_usage	Boolean
group_processes	Boolean
case_sensitive	Boolean
whole_word	Boolean
regex	Boolean
show_disabled_data	Boolean
basic	Boolean
rate	Unsigned Int (represents milliseconds)
default_time_value	Unsigned Int (represents milliseconds)
time_delta	Unsigned Int (represents milliseconds)
temperature_type	String (one of ["k", "f", "c", "kelvin", "fahrenheit", "celsius"])
default_widget_type	String (one of ["cpu", "proc", "net", "temp", "mem", "disk"], same as layout options)
default_widget_count	Unsigned Int (represents which default_widget_type)

Theming

The config file can be used to set custom colours for parts of the application under the [colors] object. The following labels are customizable with strings that are hex colours, RGB colours, or specific named colours.

Supported named colours are one of the following strings: Reset, Black, Red, Green, Yellow, Blue, Magenta, Cyan, Gray, DarkGray, LightRed, LightGreen, LightYellow, LightBlue, LightMagenta, LightCyan, White.

Labels	Details	Example
Table header colours	Colour of table headers	table_header_color="255, 255, 255"
CPU colour per core	Colour of each core. Read in order.	cpu_core_colors=["#ffffff", "white", "255, 255, 255"]
Average CPU colour	The average CPU color	avg_cpu_color="White"
RAM	The colour RAM will use	ram_color="#ffffff"
SWAP	The colour SWAP will use	swap_color="#ffffff"
RX	The colour rx will use	rx_color="#ffffff"
TX	The colour tx will use	tx_color="#ffffff"
Widget title colour	The colour of the label each widget has	widget_title_color="#ffffff"
Border colour	The colour of the border of unselected widgets	border_color="#ffffff"
Selected border colour	The colour of the border of selected widgets	highlighted_border_color="#ffffff"
Text colour	The colour of most text	text_color="#ffffff"
Graph colour	The colour of the lines and text of the graph	graph_color="#ffffff"
Cursor colour	The cursor's colour	cursor_color="#ffffff"
Selected text colour	The colour of text that is selected	scroll_entry_text_color="#ffffff"
Selected text background colour	The background colour of text that is selected	scroll_entry_bg_color="#ffffff"

Layout

bottom supports customizable layouts via the config file. Currently, layouts are controlled by using TOML objects and arrays.

For example, given the sample layout:

[[row]]
  [[row.child]]
  type="cpu"
[[row]]
    ratio=2
    [[row.child]]
      ratio=4
      type="mem"
    [[row.child]]
      ratio=3
      [[row.child.child]]
        type="temp"
      [[row.child.child]]
        type="disk"

This would give a layout that has two rows, with a 1:2 ratio. The first row has only the CPU widget. The second row is split into two columns with a 4:3 ratio. The first column contains the memory widget. The second column is split into two rows with a 1:1 ratio. The first is the temperature widget, the second is the disk widget.

This is what the layout would look like when run:

Each [[row]] represents a row in the layout. A row can have any number of child values. Each [[row.child]] represents either a column or a widget. A column can have any number of child values as well. Each [[row.child.child]] represents a widget. A widget is represented by having a type field set to a string.

The following type values are supported:

cpu	CPU chart and legend
mem	Memory chart
proc	Process table and search
net	Network chart and legend
temp	Temperature table
disk	Disk table
empty	An empty space

Each component of the layout accepts a ratio value. If this is not set, it defaults to 1.

For an example, look at the default config, which contains the default layout.

...and yes, you can have duplicate widgets. This means you could do something like:

[[row]]
  ratio=1
  [[row.child]]
  type="cpu"
  [[row.child]]
  type="cpu"
  [[row.child]]
  type="cpu"
[[row]]
  ratio=1
  [[row.child]]
  type="cpu"
  [[row.child]]
  type="empty"
  [[row.child]]
  type="cpu"
[[row]]
  ratio=1
  [[row.child]]
  type="cpu"
  [[row.child]]
  type="cpu"
  [[row.child]]
  type="cpu"

and get the following CPU donut:

Compatibility

OS	CPU	Memory	Disks	Temperature	Processes/Search	Networks
Linux	✓	✓	✓	✓	✓	✓
Windows	✓	✓	✓	✗	✓	✓
macOS	✓	✓	✓	✓	✓	✓

Contributors

Contribution is always welcome - just submit a PR! Note that I currently develop and test on stable Rust.

Thanks to all contributors (emoji key):

Marcin Wojnarowski 💻 📦

Mahmoud Al-Qudsi 💻

Thanks

• This project is very much inspired by both gotop and gtop.

• Basic mode is heavily inspired by htop's design.

• This application was written with many, many libraries, and built on the work of many talented people. This application would be impossible without their work.