bottom Documentation

Technical Documentation: ClementTsang/bottom

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (`README.md`) Copy Section

Table of contents Copy Chapter

• Features
• Support
  • Official
  • Unofficial
• Installation
  • Cargo
  • Alpine
  • Arch Linux
  • Debian / Ubuntu
  • Exherbo Linux
  • Fedora / CentOS / AlmaLinux / Rocky Linux
    • COPR
    • Terra
    • RPM
  • Gentoo
  • Nix
  • openSUSE
  • Snap
  • Solus
  • Void
  • Homebrew
  • MacPorts
  • Chocolatey
  • Scoop
  • winget
  • Windows installer (MSI)
  • Conda
  • gah
  • ghr
  • mise
  • Pre-built binaries
    • Auto-completion
• Usage
• Configuration
• Troubleshooting
• Documentation
• Contribution
  • Contributors
• Thanks

Features Copy Chapter

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

• Graphical visualization widgets for:

  • CPU usage over time, at an average and per-core level
  • RAM and swap usage over time
  • Network I/O usage over time
  • Temperature over time
  • Disk I/O usage over time

  with support for zooming in/out the current time interval displayed.

• Widgets for displaying info about:

  • Disk capacity/usage
  • Temperature sensors
  • Battery usage

• A process widget for displaying, sorting, and searching info about processes, as well as support for:

  • Kill signals
  • Tree mode

• Cross-platform support for Linux, macOS, and Windows, with more planned in the future.

• Customizable behaviour that can be controlled with command-line options or a config file, such as:

  • Custom and built-in colour themes
  • Customizing widget behaviour
  • Changing the layout of widgets
  • Filtering out entries in some widgets

• And more:

  • An htop-inspired basic mode
  • Expansion to focus on just one widget

You can find more details in the documentation.

Support Copy Chapter

Official Copy Section

bottom officially supports the following operating systems and corresponding architectures:

• macOS (x86_64, aarch64)
• Linux (x86_64, i686, aarch64)
• Windows (x86_64, i686)

These platforms are tested to work for the most part and issues on these platforms will be fixed if possible.
Furthermore, binaries are built and tested using the most recent version of stable Rust at the time.

For more details on supported platforms and known problems, check out the documentation.

Unofficial Copy Section

bottom may work on a number of platforms that aren't officially supported. Note that unsupported platforms:

• Might not be tested in CI to build or pass tests (see here for checked platforms).
• Might not be properly tested by maintainers prior to a stable release.
• May only receive limited support, such as missing features or bugs that may not be fixed.

Note that some unsupported platforms may eventually be officially supported (e.g., FreeBSD).

A non-comprehensive list of some currently unofficially-supported platforms that may compile/work include:

• FreeBSD (x86_64)
• Linux (armv6, armv7, powerpc64le, riscv64gc, loongarch64)
• Android (arm64)
• Windows (arm64)
• NetBSD (x86_64)

For more details on unsupported platforms and known problems, check out the documentation.

Installation Copy Chapter

Cargo Copy Section

Installation via cargo can be done by installing the bottom crate:

# You might need to update the stable version of Rust first.
# Other versions might work, but this is not guaranteed.
rustup update stable

# Install the binary from crates.io.
cargo install bottom --locked

# If you use another channel by default, you can specify
# the what channel to use like so:
cargo +stable install bottom --locked

# --locked may be omitted if you wish to not use the
# locked crate versions in Cargo.lock. However, be
# aware that this may cause problems with dependencies.
cargo install bottom

Alternatively, you can use cargo install using the repo as the source.

# You might need to update the stable version of Rust first.
# Other versions might work, but this is not guaranteed.
rustup update stable

# Option 1 - Download an archive from releases and install
curl -LO https://github.com/ClementTsang/bottom/archive/0.14.9.tar.gz
tar -xzvf 0.14.9.tar.gz
cargo install --path . --locked

# Option 2 - Manually clone the repo and install
git clone https://github.com/ClementTsang/bottom
cd bottom
cargo install --path . --locked

# Option 3 - Install using cargo with the repo as the source
cargo install --git https://github.com/ClementTsang/bottom --locked

# You can also pass in the target-cpu=native flag to try to
# use better CPU-specific optimizations. For example:
RUSTFLAGS="-C target-cpu=native" cargo install --path . --locked

Alpine Copy Section

bottom is available as a package for Alpine Linux via apk:

apk add bottom

Packages for documentation (bottom-doc) and completions for Bash (bottom-bash-completion), Fish (bottom-fish-completion), and Zsh (bottom-zsh-completion) are also available.

Arch Linux Copy Section

bottom is available as an official package that can be installed with pacman:

sudo pacman -S bottom

If you want the latest changes that are not yet stable, you can also install bottom-git from the AUR:

# Using paru
paru -S bottom-git

# Using yay
yay -S bottom-git

Debian / Ubuntu Copy Section

A .deb file is provided on each stable release and
nightly builds for x86, aarch64, and armv7.
Some examples of installing it this way:

# x86-64
curl -LO https://github.com/ClementTsang/bottom/releases/download/0.14.9/bottom_0.14.9-1_amd64.deb
sudo dpkg -i bottom_0.14.9-1_amd64.deb

# ARM64
curl -LO https://github.com/ClementTsang/bottom/releases/download/0.14.9/bottom_0.14.9-1_arm64.deb
sudo dpkg -i bottom_0.14.9-1_arm64.deb

# ARM
curl -LO https://github.com/ClementTsang/bottom/releases/download/0.14.9/bottom_0.14.9-1_armhf.deb
sudo dpkg -i bottom_0.14.9-1_armhf.deb

# musl-based
curl -LO https://github.com/ClementTsang/bottom/releases/download/0.14.9/bottom-musl_0.14.9-1_amd64.deb
sudo dpkg -i bottom-musl_0.14.9-1_amd64.deb

Exherbo Linux Copy Section

bottom is available as a rust package that can be installed with cave:

cave resolve -x repository/rust
cave resolve -x bottom

Fedora / CentOS / AlmaLinux / Rocky Linux Copy Section

COPR

[!WARNING]

atim/bottom seems to be unmaintained and may be outdated (relevant issue)

bottom is available on COPR:

sudo dnf copr enable atim/bottom -y
sudo dnf install bottom

Terra

bottom is also available via Terra:

sudo dnf install --repofrompath 'terra,https://repos.fyralabs.com/terra$releasever' --setopt='terra.gpgkey=https://repos.fyralabs.com/terra$releasever/key.asc' terra-release
sudo dnf install bottom

RPM

.rpm files are also generated for x86 in the releases page.
For example:

curl -LO https://github.com/ClementTsang/bottom/releases/download/0.14.9/bottom-0.14.9-1.x86_64.rpm
sudo dnf install ./bottom-0.14.9-1.x86_64.rpm

Gentoo Copy Section

Available in the official Gentoo repo:

sudo emerge --ask sys-process/bottom

Nix Copy Section

Available in Nixpkgs as bottom:

nix profile install nixpkgs#bottom

bottom can also be installed and configured through the home-manager module:

{
  programs.bottom.enable = true;
}

openSUSE Copy Section

Available in openSUSE Tumbleweed:

zypper in bottom

Snap Copy Section

bottom is available as a snap:

sudo snap install bottom

# To allow the program to run as intended
sudo snap connect bottom:mount-observe
sudo snap connect bottom:hardware-observe
sudo snap connect bottom:system-observe
sudo snap connect bottom:process-control

Solus Copy Section

Available in the Solus repos:

sudo eopkg it bottom

Void Copy Section

Available in the void-packages repo:

sudo xbps-install bottom

Homebrew Copy Section

The formula is available here:

brew install bottom

MacPorts Copy Section

Available here:

sudo port selfupdate
sudo port install bottom

Chocolatey Copy Section

Chocolatey packages are located here:

choco install bottom

Scoop Copy Section

Available in the Main bucket:

scoop install bottom

winget Copy Section

The winget package can be found here:

winget install bottom

# If you need a more specific app id:
winget install Clement.bottom

You can uninstall via Control Panel, Options, or winget --uninstall bottom.

Windows installer (MSI) Copy Section

You can manually install bottom as a Windows program by downloading and using the .msi file from the latest release.

Conda Copy Section

You can install bottom using conda with this conda-smithy repository:

# Add the channel
conda config --add channels conda-forge
conda config --set channel_priority strict

# Install
conda install bottom

gah Copy Section

bottom can also be installed on Linux or macOS using gah:

gah install bottom

ghr Copy Section

bottom can be installed using ghr like so:

ghr install clementtsang/bottom

mise Copy Section

bottom is available via mise:

mise use -g bottom@latest

Pre-built binaries Copy Section

You can also use the pre-built release binaries:

• Latest stable release
• Latest nightly release

To use, download and extract the binary that matches your system. You can then run by doing:

./btm

or by installing to your system following the procedures for installing binaries to your system.

Auto-completion

The release binaries in the releases page are packaged with
shell auto-completion files for Bash, Zsh, fish, Powershell, Elvish, Fig, and Nushell. To install them:

• For Bash, move btm.bash to $XDG_CONFIG_HOME/bash_completion or /etc/bash_completion.d/.
• For Zsh, move _btm to one of your $fpath directories.
• For fish, move btm.fish to $HOME/.config/fish/completions/.
• For PowerShell, add _btm.ps1 to your PowerShell profile.
• For Elvish, the completion file is btm.elv.
• For Fig, the completion file is btm.ts.
• For Nushell, use btm.nu.

The individual auto-completion files are also included in the stable/nightly releases as completion.tar.gz if needed.

Usage Copy Chapter

You can run bottom using btm.

• For help on flags, use btm -h for a quick overview or btm --help for more details.
• For info on key and mouse bindings, press ? inside bottom or refer to the documentation page.

You can find more information on usage in the documentation.

Configuration Copy Chapter

bottom accepts a number of command-line arguments to change the behaviour of the application as desired.
Additionally, bottom will automatically generate a configuration file on the first launch, which can be changed.

More details on configuration can be found in the documentation.

Troubleshooting Copy Chapter

If some things aren't working, give the troubleshooting page
a look. If things still aren't working, then consider asking a question
or filing a bug report if you think it's a bug.

Documentation Copy Chapter

The main documentation page can be found at https://bottom.pages.dev, using Cloudflare Pages. If needed, a mirror hosted using
Github Pages is also available at https://clementtsang.github.io/bottom.

Contribution Copy Chapter

Whether it's reporting bugs, suggesting features, maintaining packages, or submitting a PR, contribution is always welcome! Please read
CONTRIBUTING.md for details on how to contribute to bottom.

Contributors Copy Section

Thanks to all contributors:

Thanks Copy Chapter

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

• This application was written with many,
  many libraries, as well as many services and
  programs, all built on top of the work of many talented people. bottom would not exist without all of this.

• And of course, thank you again to all contributors and package maintainers!

• I also really appreciate anyone who has used bottom, and those
  who go out of their way to report bugs or suggest ways to improve things. I hope
  it's been a useful tool for others.

• To those who support my work financially via donations, thank you so much.

• Thanks to JetBrains for providing access to tools that I use to develop bottom
  as part of their open source support program.

• Also thanks to SignPath.io for providing a free code signing service, and to the
  SignPath Foundation for the certificate.

Overview (`docs/README.md`) Copy Section

Extended Documentation

This is where the extended documentation resides, hosted on GitHub Pages. We use MkDocs,
Material for MkDocs, and mike.

Documentation is currently built using Python 3.11, though it should work fine with older versions.

Running locally Copy Chapter

One way is to just run serve.sh. Alternatively, the manual steps are, assuming your current working directory
is the bottom repo:

# Change directories to the documentation.
cd docs/

# Create and activate venv.
python -m venv venv
source venv/bin/activate

# Install requirements
pip install -r requirements.txt

# Run mkdocs
venv/bin/mkdocs serve

Deploying Copy Chapter

Deploying is done via mike in order to get versioning. Typically,
this is done through CI, but can be done manually if needed.

Nightly docs Copy Section

cd docs
mike deploy nightly --push

Stable docs Copy Section

cd docs

# Rename the previous stable version
mike retitle --push stable $OLD_STABLE_VERSION

# Set the newest version as the most recent stable version
mike deploy --push --update-aliases $RELEASE_VERSION stable

# Append a "(stable)" string to the end.
mike retitle --push $RELEASE_VERSION "$RELEASE_VERSION (stable)"

Overview (`schema/README.md`) Copy Section

Config JSON Schema

Generation Copy Chapter

These are automatically generated from the code using schemars. The schemars
derives are locked behind the generate_schema feature flag to avoid building unnecessary code for normal builds.
Meanwhile, the generator itself lives in a separate scripts/schema_gen helper crate. You can
generate them like so:

# Will print out to stdout
cargo run --manifest-path scripts/schema_gen/Cargo.toml

# e.g. for nightly
cargo run --manifest-path scripts/schema_gen/Cargo.toml > schema/nightly/bottom.json

# e.g. for a specific version
cargo run --manifest-path scripts/schema_gen/Cargo.toml -- 0.12.0 > schema/v0.12.0/bottom.json

Alternatively, run the scripts/schema/generate.sh script (for stable releases) or scripts/schema/nightly.sh
(for nightly), which does all of this for you.

Publication Copy Chapter

To publish these schemas:

Stable Copy Section

1. Run scripts/schema/generate.sh <YOUR_VERSION>.
2. Make a PR and merge it.
3. Then, make a PR to schemastore to update the catalog.
   Here's an example of a PR.

Nightly Copy Section

1. Run scripts/schema/nightly.sh.
2. Make a PR and merge it.

Overview (`scripts/hooks/README.md`) Copy Section

Git Hooks

Optional pre-push git hook. These are checked again in CI anyway, but may make it easier to check for issues upfront pre-push.

Overview (`scripts/schema_gen/README.md`) Copy Section

schema_gen

This is just a tool to automatically generate JSON Schema for bottom's config.

Content Index (`docs/content/index.md`) Copy Section

hide:

• navigation
• toc
  title: Home

`bottom`

A customizable cross-platform graphical process/system monitor for the terminal, supporting Linux, macOS, and Windows. Inspired by other tools like gtop, gotop, and htop.

This site serves as extended documentation for bottom alongside the README.md.

!!! Warning

Some areas of this site are still in progress and may be missing details.  Feel free to suggest/contribute changes!

Installation Copy Chapter

!!! Tip

It's as good idea to first check out the [Support](support/official.md) page to see if your system is officially supported!

!!! Tip

If you're facing some issues during/after installation, check out the [Troubleshooting](troubleshooting.md) page for some common problems and solutions.

To install bottom, refer to the installation section of the README.md,
which contains a list of all the installation methods.

Usage and configuration Copy Chapter

The command to run bottom is btm.

You can refer to the usage pages for more details on using bottom (e.g. keybinds, some features, a general overview of what each widget does).

To configure bottom (e.g. how it behaves, how it looks, etc.) refer to the command-line options page for temporary settings, or the config file page for more permanent settings.

Contribution Copy Chapter

New contributors are always welcome! See the contribution section for how to contribute to
bottom, whether it be filing issues, writing documentation, creating pull requests, etc.

Content Configuration Config File Index (`docs/content/configuration/config-file/index.md`) Copy Section

Config File

For persistent configuration, and for certain configuration options, bottom supports config files.

Default Config File Copy Chapter

If no config file argument is given, it will automatically look for a config file at these locations:

If the config file doesn't exist at the path, bottom will automatically try to create a new config file at the location
with default values.

JSON Schema Copy Chapter

The configuration file also has JSON Schema support to make it easier to manage, if your
IDE/editor supports it.

Mkdocs.Yml (`docs/mkdocs.yml`) Copy Section

Site information

site_name: bottom
site_author: Clement Tsang
site_url: https://bottom.pages.dev
site_description: >-
A customizable cross-platform graphical process/system monitor for the
terminal. Supports Linux, macOS, and Windows.
docs_dir: "content/"

Project information

repo_name: ClementTsang/bottom
repo_url: https://github.com/ClementTsang/bottom
edit_uri: "edit/main/docs/content/"
copyright: Copyright © 2019 - 2026 Clement Tsang

Theming

theme:
name: material
font:
code: IBM Plex Mono
features:
- content.action.edit
- navigation.expand
- navigation.footer
- navigation.indexes
- navigation.instant
- navigation.instant.progress
- navigation.sections
- navigation.tabs
- navigation.top
- search.highlight
- search.suggest
- toc.integrate
- toc.follow
icon:
edit: material/pencil
palette:
# Palette toggle for automatic mode
- media: "(prefers-color-scheme)"
scheme: default
toggle:
icon: material/brightness-auto
name: Switch to light mode
# Light mode
- media: "(prefers-color-scheme: light)"
primary: indigo
accent: indigo
toggle:
icon: material/weather-sunny
name: Switch to dark mode
# Dark mode
- media: "(prefers-color-scheme: dark)"
scheme: slate
primary: black
accent: indigo
toggle:
icon: material/weather-night
name: Switch to system preference
custom_dir: "overrides"
extra_css:

• stylesheets/extra.css

Extensions

markdown_extensions:

• admonition
• attr_list
• toc:
  anchorlink: true
• pymdownx.inlinehilite
• pymdownx.keys:

  Override to make it case-sensitive

  key_map:
  {
  "a": "a",
  "b": "b",
  "c": "c",
  "d": "d",
  "e": "e",
  "f": "f",
  "g": "g",
  "h": "h",
  "i": "i",
  "j": "j",
  "k": "k",
  "l": "l",
  "m": "m",
  "n": "n",
  "o": "o",
  "p": "p",
  "q": "q",
  "r": "r",
  "s": "s",
  "t": "t",
  "u": "u",
  "v": "v",
  "w": "w",
  "x": "x",
  "y": "y",
  "z": "z",
  "A": "A",
  "B": "B",
  "C": "C",
  "D": "D",
  "E": "E",
  "F": "F",
  "G": "G",
  "H": "H",
  "I": "I",
  "J": "J",
  "K": "K",
  "L": "L",
  "M": "M",
  "N": "N",
  "O": "O",
  "P": "P",
  "Q": "Q",
  "R": "R",
  "S": "S",
  "T": "T",
  "U": "U",
  "V": "V",
  "W": "W",
  "X": "X",
  "Y": "Y",
  "Z": "Z",
  }
• pymdownx.details
• pymdownx.highlight
• pymdownx.superfences
• mdx_truly_sane_lists # See https://github.com/mkdocs/mkdocs/issues/545#issuecomment-522196661
• pymdownx.tabbed:
  alternate_style: true

plugins:

• tags
• search
• mike:
  canonical_version: stable
• git-revision-date-localized:
  type: date
• privacy
• redirects:
  redirect_maps:
  nightly-release.md: "https://github.com/ClementTsang/bottom/releases"

extra:

Versioning

version:
provider: mike
default: stable
alias: true

Used for the nightly banner

nightly: false

Navigation

nav:

• "Home": index.md
• "Support":
  • "Official Support": support/official.md
  • "Unofficial Support": support/unofficial.md
• "Usage":
  • "General Usage": usage/general-usage.md
  • "Basic Mode": usage/basic-mode.md
  • "Widgets":
    • "CPU Widget": usage/widgets/cpu-graph.md
    • "Memory Graph Widget": usage/widgets/memory-graph.md
    • "Network Graph Widget": usage/widgets/network-graph.md
    • "Process Widget": usage/widgets/process.md
    • "Disk Widget": usage/widgets/disk.md
    • "Temperature Widget": usage/widgets/temperature-table.md
    • "Temperature Graph Widget": usage/widgets/temperature-graph.md
    • "Disk I/O Graph Widget": usage/widgets/disk-io-graph.md
    • "Battery Widget": usage/widgets/battery.md
  • "Auto-Complete": usage/autocomplete.md
• "Configuration":
  • "Command-line Options": configuration/command-line-options.md
  • "Config File":
    • configuration/config-file/index.md
    • "CPU Widget": configuration/config-file/cpu-graph.md
    • "Disk Table Widget": configuration/config-file/disk-table.md
    • "Memory Graph Widget": configuration/config-file/memory-graph.md
    • "Network Graph Widget": configuration/config-file/network-graph.md
    • "Processes Widget": configuration/config-file/processes.md
    • "Temperature Table Widget": configuration/config-file/temperature-table.md
    • "Temperature Graph Widget": configuration/config-file/temperature-graph.md
    • "Disk I/O Graph Widget": configuration/config-file/disk-io-graph.md
    • "Flags": configuration/config-file/flags.md
    • "Layout": configuration/config-file/layout.md
    • "Styling": configuration/config-file/styling.md
• "Contribution":
  • "Issues, Pull Requests, and Discussions": contribution/issues-and-pull-requests.md
  • "Documentation": contribution/documentation.md
  • "Packaging and Distribution": contribution/packaging-and-distribution.md
  • "Development":
    • "Development Environment": contribution/development/dev_env.md
    • "Testing": contribution/development/testing.md
    • "Logging": contribution/development/logging.md
    • "Build Process": contribution/development/build_process.md
    • "Deploy Process": contribution/development/deploy_process.md
• "Troubleshooting": troubleshooting.md

hooks:

• ./hooks/nightly_redirect.py
• ./hooks/nightly_banner.py

exclude_docs: |
nightly-release.md

Requirements (`docs/requirements.txt`) Copy Section

TODO: We may want to migrate off of mkdocs since mkdocs-material is

now on maintenance mode... this might be kinda hard to do though.

mkdocs == 1.6.1
mkdocs-material == 9.7.7
mdx_truly_sane_lists == 1.3
mike == 2.1.4
mkdocs-git-revision-date-localized-plugin == 1.4.5
mkdocs-redirects == 1.2.2

Content Troubleshooting (`docs/content/troubleshooting.md`) Copy Section

Troubleshooting/Known Issues

The graph points look broken/strange Copy Chapter

It's possible that your graphs don't look great out of the box due to the reliance on
braille characters to draw them. This could cause problems if
your terminal's font does not support them, or your terminal is not configured properly to draw them.

<figcaption><sub>An example of missing braille fonts in Powershell</sub></figcaption>

Some possible solutions are included below.

Use dot markers instead Copy Section

One alternative is to use the --dot_marker option to render graph charts using dots instead of the braille characters,
which generally seems better supported out of the box, at the expense of looking less intricate:

<figcaption><sub>Example using `btm --dot_marker`</sub></figcaption>

Use a font that supports braille fonts Copy Section

Another (better) alternative is to install a font that supports braille fonts, and configure your terminal emulator to
use it. For example, installing something like UBraille or
Iosevka and ensuring your terminal uses it should work.

Linux/macOS/Unix

Solutions mostly depend on what terminal emulator you are using, so unfortunately, I can't give specific instructions.
Here are some possible solutions:

• Uninstalling gnu-free-fonts if installed, as that is known to cause problems with braille markers
• Installing a font like ttf-symbola or ttf-ubraille for your terminal emulator to try and automatically fall back to
• Configuring your terminal emulator to use specific fonts for the U+2800 to U+28FF range.
  • For example for kitty, do symbol_map U+2800-U+28FF Symbola.

For some more possible solutions:

• Check out this issue from gotop about the same issue.
• See ratatui's FAQ (ratatui is the underlying
  library bottom uses to draw things).

Windows and Powershell

Note: I would advise backing up your registry beforehand if you aren't sure what you are doing!

Let's say you're installing Iosevka. The steps you can take are:

1. Install the font itself.

2. Open the registry editor, which you can do either by Win+R and opening regedit, or just opening it from the Start Menu.

3. In the registry editor, go to

   text Copy

   HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Console\TrueTypeFont

4. Here, add a new String value, and set the Name to a bunch of 0's (e.g. 000 - make sure the name isn't already used), then set the Data to the font name (e.g. Iosevka).

   text Copy

   <figcaption><sub>The last entry is the new entry for Iosevka</sub></figcaption>

5. Then, open the Command Prompt/PowerShell, and right-click on the top bar, and open "Properties":

6. From here, go to "Font", and set the font to your new font (so in this example, Iosevka):

Why can't I see all my temperature sensors on Windows? Copy Chapter

This is a known issue, some sensors may require admin privileges to get sensor data.

Why don't I see dual batteries on Windows reported separately? (e.g. Thinkpads) Copy Chapter

This is a known issue which seems to be with how batteries are being detected on Windows.

Why can't I see all my temperature sensors on WSL? Copy Chapter

This is a known limitation with WSL. Due to how it works, hosts may not expose their
temperature sensors and therefore, temperature sensors might be missing.

Why does WSL2 not match Task Manager? Copy Chapter

This is a known limitation with WSL2. Due to how WSL2 works, the two might not match
up in terms of reported data.

Why can't I see all my processes/process data on macOS? Copy Chapter

You may have to run the program with elevated privileges to work around it - for example:

sudo btm

!!! Warning

Please note that you should be certain that you trust any software you grant root privileges.

There are measures taken to try to maximize the amount of information obtained without elevated privileges. For example,
one can modify the instructions found on the [htop wiki](https://github.com/hishamhm/htop/wiki/macOS:-run-without-sudo)
on how to run htop without sudo for bottom. However, **please** understand the potential security risks before doing so!

My configuration file isn't working Copy Chapter

If your configuration files aren't working, here are a few things to try:

Check the formatting Copy Section

It may be handy to refer to the automatically generated config files or the
sample configuration files. The config files also
follow the TOML format.

Also make sure your config option settings are in the right location - for example, to set your temperature type, you must
set it under the [flags] table:

[flags]
temperature_type = "f"

Meanwhile, if you want to set a custom colour or styling scheme, it would be under the [styles] table - for example:

[styles.tables.headers]
colour = "LightBlue"
bold = true

To help validate your configuration files, there is JSON Schema support if your IDE/editor
supports it.

Check the configuration file location Copy Section

Make sure bottom is reading the right configuration file. By default, bottom looks for config files at these locations:

If you want to use a config file in another location, use the --config or -C flags along with the path to the configuration file, like so:

btm -C path_to_config

My installation through snap has some widgets that are blank/show no data Copy Chapter

Make sure bottom is given the correct permissions in order to collect data. Snapcraft
explains how to do so, but the TL;DR is:

sudo snap connect bottom:mount-observe
sudo snap connect bottom:hardware-observe
sudo snap connect bottom:system-observe
sudo snap connect bottom:process-control

I don't see any NVIDIA GPU information while using a musl-based binary Copy Chapter

The underlying interface we use for NVIDIA GPU information, nvml, only works with glibc and does not work with musl at the moment (see this forum post for some more details). As such, bottom may fail to get NVIDIA GPU information when using a musl-based binary until this is resolved. This applies to Linux and Windows from my understanding.

To resolve this, use glibc-based binary builds if possible (e.g. the gnu binaries/non-musl packages in releases).

Still having issues? Copy Chapter

If you're still having issues, feel free to open a discussion
question about it, and I (or others) can try to help.

Content Configuration Command Line Options (`docs/content/configuration/command-line-options.md`) Copy Section

Command-line Options

The following options can be provided to bottom in the command line to change the behaviour of the program. You can also
see information on these options by running btm -h, or run btm --help to display more detailed information on each option:

General Options Copy Chapter

Disk Options Copy Chapter

Process Options Copy Chapter

Temperature Options Copy Chapter

CPU Options Copy Chapter

Memory Options Copy Chapter

Network Options Copy Chapter

Battery Options Copy Chapter

GPU Options Copy Chapter

Style Options Copy Chapter

Other Options Copy Chapter

Content Contribution Documentation (`docs/content/contribution/documentation.md`) Copy Section

Documentation

When should documentation changes be done? Copy Chapter

• Whenever a new feature is added, a bug is fixed, or a breaking change is made, it should be documented where
  appropriate (ex: README.md, changelog, etc.)
• New methods of installation are always appreciated and should be documented

What pages need documentation? Copy Chapter

There are a few areas where documentation changes are often needed:

• The README.md
• The help menu inside of the application (located here)
• The extended documentation (what you're reading right now)
• The CHANGELOG.md

How should I add/update documentation? Copy Chapter

1. Fork the repository to make changes in.

2. Where you're adding documentation will probably affect what you need to do:

   `README.md` or `CHANGELOG.md`

   For changes to README.md and CHANGELOG.md, just follow the formatting provided and use any editor.

   Generally, changes to CHANGELOG.md will be handled
   by a maintainer, and the contents of the file should follow the Keep a Changelog
   format, as well as link to the relevant PR or issues.

   Help menu

   For changes to the help menu, try to refer to the existing code within src/constants.rs on how the help menu is generated.

   Extended documentation

   For changes to the extended documentation, you'll probably want at least Python 3.11 (older and newer versions
   should be fine), MkDocs, Material for MkDocs,
   mdx_truly_sane_lists, and optionally Mike installed. These can help with
   validating your changes locally.

   You can do so through pip or your system's package managers. If you use pip, you can use venv to cleanly install
   the documentation dependencies:

   bash Copy

   # Change directories to the documentation.
   cd docs/
   
    # Create venv, install the dependencies, and serve the page.
   ./serve.sh

   This will serve a local version of the docs that you can open on your browser. It will update as you make changes.

3. Once you have your documentation changes done, submit it as a pull request. For more information regarding that,
   refer to Issues, Pull Requests, and Discussions.

AI Policy Copy Chapter

Documentation should never be generated by AI. The point of documentation in this project is to communicate things between humans. Follow the AI policy; changes that do not follow it
may be closed or hidden.

Content Contribution Issues And Pull Requests (`docs/content/contribution/issues-and-pull-requests.md`) Copy Section

Issues, Pull Requests, and Discussions

Discussions Copy Chapter

Discussions are open in the repo. As for the difference between discussions and issues:

• Open an issue if what you have enough information to properly fill out any details needed for a report or request.
• Open a discussion otherwise (e.g. asking a question).

Opening an issue Copy Chapter

Bug reports Copy Section

When filing a bug report, please use the bug report template and fill in as much as you can. It is incredibly difficult for a maintainer to fix a bug when it cannot be reproduced, and giving as much detail as possible generally helps to make it easier to reproduce the problem!

Feature requests Copy Section

Please use the feature request template and fill it out. Remember to give details about what the feature is along with why you think this suggestion will be useful first! Also, please check whether an existing issue
already covers your specific feature request.

Pull requests Copy Chapter

Note: if you want to add a new feature, please first open an appropriate issue to discuss the merits of the feature.
PRs that do not do this may be closed.

The expected workflow for a pull request is:

1. Fork the project.
2. Make your changes.
3. Make any documentation changes if necessary - if you add a new feature, it'll probably need documentation changes. See here for tips on documentation.
4. Commit and create a pull request to merge into the main branch. Please fill out the pull request template and checklist.
5. Ask a maintainer to review your pull request.
   • Check if the CI workflow passes. These consist of clippy lints, rustfmt checks, and basic tests. If you are a
     first-time contributor, you may need to wait for a maintainer to let CI run.
   • If changes are suggested or any comments are made, they should probably be addressed.
6. Once it looks good, it'll be merged! Note that generally, PRs are squashed to maintain repo cleanliness, though
   feel free to ask otherwise if that isn't preferable.

Some other things related to making changes or pull requests:

• Please review your code yourself and test your changes before you create the PR and ask for a review.
• If you are adding or changing any dependency, a justification on why this is necessary must be included.
• Please ensure that any changes made are compatible with the license of bottom.

AI Policy Copy Chapter

Note that any contribution, whether it be opening an issue, PRs, or commenting, should follow the AI policy. Contributions that do not follow this may be closed/hidden.

Content Contribution Packaging And Distribution (`docs/content/contribution/packaging-and-distribution.md`) Copy Section

Packaging and Distribution

Package maintainers are always welcome and appreciated! Here's some info on how one can help with package distribution
and bottom.

Pre-built binaries Copy Chapter

The latest stable release can be found here, where you can
find pre-built binaries in either a tar.gz or zip format. Binaries here also include automatically generated shell
completion files for zsh, bash, fish, and Powershell, which you may want to also install during the packaging
process.

You can also find a nightly build in the releases page, built every
day at 00:00 UTC off of the main branch.

In both cases, we use GitHub Actions to create our release binaries.
build_releases.yml
contains the GitHub Action workflow for this.

Building manually Copy Chapter

If you want to manually build bottom rather than distributing a pre-built binary, you'll need the most recent version
of stable Rust, which you can get with:

rustup update stable

You'll then want to build with:

cargo build --release --locked

Manpage and completion generation Copy Section

bottom uses a build.rs script to automatically generate
a manpage and shell completions for the following shells:

• Bash
• Zsh
• Fish
• Powershell
• Elvish

If you want to generate manpages and/or completion files, set the BTM_GENERATE env var to a non-empty value. For
example, run something like this:

BTM_GENERATE=true cargo build --release --locked

This will automatically generate completion and manpage files in target/tmp/bottom/. If you wish to regenerate the
files, modify/delete either these files or set BTM_GENERATE to some other non-empty value to retrigger the build
script.

You may override the default directories used to generate both completion and manpage files by specifying the
COMPLETION_DIR and MANPAGE_DIR environment variables respectively.

For more information, you may want to look at either the build.rs
file or the binary build CI workflow.

Adding an installation source Copy Chapter

Once you've finished your installation source, if you want to mention it in the main bottom repo, fork the repo and add
the installation method and any details to the README.md
file under the Installation section, as well as a corresponding
table of contents entry. Once that's done, open a pull request - these will usually be approved of very quickly.

You can find more info on the contribution process here.

Content Support Official (`docs/content/support/official.md`) Copy Section

Official support

bottom officially supports the following operating systems and corresponding architectures:

• macOS (x86_64, aarch64)
• Linux (x86_64, i686, aarch64)
• Windows (x86_64, i686)

These platforms are tested to work (with caveats, see below) and issues on these platforms will be fixed if possible.

Furthermore, binaries are expected to be built and tested using the most recent version of stable Rust - if you are manually building
bottom from the repo/source, then please try that as well.

If you encounter any issues, see the troubleshooting page or open an issue/discussion on GitHub.

Content Support Unofficial (`docs/content/support/unofficial.md`) Copy Section

Unofficial support

Systems and architectures that aren't officially supported may still work, but there are no guarantees on how much will
work. For example, it might only compile, or it might run with bugs/broken features. Furthermore, while it will depend
on the problem at the end of the day, issues on unsupported platforms are likely to go unfixed.

Unofficially supported platforms known to compile/work:

• FreeBSD on x86 (built and tested in CI)
• Linux on ARMv7 and ARMv6 (built in CI)
• Linux on PowerPC 64 LE (built in CI)
• Linux on an RISC-V (built in CI, tested to run on an Allwinner D1 Nezha)
• NetBSD on x86 (built in CI)

If you encounter any issues, see the troubleshooting page or open an issue/discussion on
GitHub - though as mentioned, unsupported platforms may go unfixed.

Content Usage Autocomplete (`docs/content/usage/autocomplete.md`) Copy Section

Auto-Complete

The release binaries in the releases page are packaged with
shell auto-completion files for Bash, Zsh, fish, Powershell, Elvish, Fig, and Nushell. To install them:

• For Bash, move btm.bash to $XDG_CONFIG_HOME/bash_completion or /etc/bash_completion.d/.
• For Zsh, move _btm to one of your $fpath directories.
• For fish, move btm.fish to $HOME/.config/fish/completions/.
• For PowerShell, add _btm.ps1 to your PowerShell profile.
• For Elvish, the completion file is btm.elv.
• For Fig, the completion file is btm.ts.
• For Nushell, source btm.nu.

The individual auto-completion files are also included in the stable/nightly releases as completion.tar.gz if needed.

Content Usage Basic Mode (`docs/content/usage/basic-mode.md`) Copy Section

Basic Mode

Basic mode is a special layout that removes all of the graphs and provides an interface that resembles (a very stripped-down version of) htop.

Basic mode can be enabled either through a command line flag:

btm -b

# or

btm --basic

or through the config:

[flags]
basic = true

Notes Copy Chapter

In this mode, widgets that use tables (temperatures, processes, disks, and batteries) are only shown one at a time.
One can switch between these widgets either by clicking the arrow buttons or by using the general widget selection shortcuts (for example, ++ctrl+left++ or ++H++)
to switch which widget is shown.

Also note that in this mode, widget expansion and custom layouts are disabled.

Key bindings Copy Chapter

Basic mode follows the same key bindings as normal, barring widget expansion being disabled, and that the ++"%"++ key while selecting the memory widget toggles between total usage and percentage.

Content Usage General Usage (`docs/content/usage/general-usage.md`) Copy Section

General Usage

You can run bottom with:

btm

For help regarding the command-line options, use:

# For a simple overview of flags
btm -h

# For more details
btm --help

You can also see keybinds and basic usage details in bottom by pressing ++question++, which will open a help menu.

Features Copy Chapter

Expansion Copy Section

By default, bottom is somewhat like a dashboard - a bunch of different widgets, all showing different things, and they all cram together to fit into one terminal.

If you instead just want to see one widget - maybe you want to look at a graph in more detail, for example - you can "expand" the currently selected
widget using the ++e++ key, which will hide all other widgets and make that widget take up all available terminal space.

You can leave this state by either pressing ++e++ again or pressing ++esc++.

Widget selection Copy Section

To allow for widget-specific keybindings and expansion, there is the idea of widget selection in bottom, where you can focus on a specific widget to work with it.
This can be done with the mouse (just click on the widget of interest) or keyboard (ex: ++ctrl+"Direction"++, see Key bindings for alternatives).

Key bindings Copy Chapter

These are global or common keyboard shortcuts for the application, which you can see in-app through the ++question++ shortcut.
Note that key bindings are generally case-sensitive.

Mouse bindings Copy Chapter

Content Configuration Config File Cpu Graph (`docs/content/configuration/config-file/cpu-graph.md`) Copy Section

CPU Configuration

If you want to change some of the default behaviour of the CPU graph widget, you can configure things under the [cpu] section.

Default CPU graph selection Copy Chapter

You can configure which CPU graph is shown by default on startup by setting cpu.default. Defaults to "all", which
shows all entries.

[cpu]
# One of "all" (default), "average"/"avg"
default = "average"

Show decimal Copy Chapter

You can configure whether CPU usage values are shown with a decimal place by setting cpu.show_decimal. Defaults
to false.

[cpu]
show_decimal = true

Hide average CPU entry Copy Chapter

You can hide the average CPU entry entirely by setting cpu.hide_avg_cpu. Defaults to false.

[cpu]
hide_avg_cpu = true

Place legend on the left Copy Chapter

You can place the CPU chart legend on the left side by setting cpu.left_legend. Defaults to false.

[cpu]
left_legend = true

Average CPU row Copy Chapter

In basic mode, you can give the average CPU entry a dedicated row by setting cpu.basic_average_cpu_row. Defaults to false.

[cpu]
basic_average_cpu_row = true

Content Configuration Config File Disk Io Graph (`docs/content/configuration/config-file/disk-io-graph.md`) Copy Section

Disk I/O Graph Configuration

The disk I/O graph widget is configured under [disk_io_graph].

Showing Read/Write Lines Copy Chapter

By default, both the read and write rate lines are shown. They can be toggled off independently.

[disk_io_graph]
# Whether to show the read rate line. Defaults to true.
show_read = true

# Whether to show the write rate line. Defaults to true.
show_write = true

Legend Labels Copy Chapter

By default, legend entries are labelled by disk name (e.g. sda, nvme0n1). To use mount points
instead (e.g. /, /home):

[disk_io_graph]
legend = "mount"

Valid values are "disk" (default) and "mount".

Logarithmic Scale Copy Chapter

The y-axis can be switched to a logarithmic scale:

[disk_io_graph]
use_log = true

Legend Position Copy Chapter

The location of the legend can be set with legend_position. Valid values are none, top-left, top, top-right,
left, right, bottom-left, bottom, and bottom-right. Defaults to top-right.

[disk_io_graph]
legend_position = "top-right"

Show Unmounted Devices (Linux only) Copy Chapter

By default, only mounted devices are shown. To also show unmounted devices on Linux, enable include_unmounted:

[disk_io_graph]
include_unmounted = true

Filtering Entries Copy Chapter

You can filter out what entries to show by configuring [disk_io_graph.name_filter] and [disk_io_graph.mount_filter] to filter by
name and mount point respectively. In particular, you can set a list of things to filter with by setting list,
and configure how that list is processed with the other options.

If we wanted to ignoring any entry with a name that matches /dev/sda:

[disk_io_graph.name_filter]
# Whether to ignore any matches. Defaults to true.
is_list_ignored = true

# A list of filters to try and match.
list = ["/dev/sda"]

# Whether to use regex. Defaults to false.
regex = true

# Whether to be case-sensitive. Defaults to false.
case_sensitive = false

# Whether to require matching the whole word. Defaults to false.
whole_word = false

Content Configuration Config File Disk Table (`docs/content/configuration/config-file/disk-table.md`) Copy Section

Disk Table Configuration

Columns Copy Chapter

You can configure which columns are shown by the disk table widget by setting the columns setting:

[disk]
# Pick which columns you want to use in any order.
columns = ["Disk", "Mount", "Used", "Free", "Total", "Used%", "R/s", "W/s"]

Default Sort Column Copy Chapter

You can customize the default sort column (by default, it sorts by disk name in ascending order). For example, to sort by the read rate:

[disk]
default_sort = "R/s"

You can use any valid column name here (e.g. "Disk", "Mount", etc.). Note that if you put a column name that
is not actually used, the default sort will just be the first column shown.

You can also set the sort order by changing disk.sort_order with "Ascending" or "Descending". Defaults to
"Ascending":

[disk]
sort_order = "Ascending"

Using Binary Prefixes Copy Chapter

Disk space uses decimal prefixes (e.g. KB, MB, GB, TB) by default. To display using binary prefixes instead
(e.g. KiB, MiB, GiB, TiB), enable use_binary_prefix:

[disk]
use_binary_prefix = true

Show Unmounted Devices (Linux only) Copy Chapter

By default, only mounted devices are shown. To also show unmounted devices on Linux, enable include_unmounted:

[disk]
include_unmounted = true

Unmounted devices show I/O activity but have no used/free space (those require a live mount), so those
columns appear as N/A. Pseudo-devices (loop*, ram*, zram*) are skipped, and you can hide other
noisy devices with the name filter.

Filtering Entries Copy Chapter

You can filter out what entries to show by configuring [disk.name_filter] and [disk.mount_filter] to filter by name and mount point respectively. In particular,
you can set a list of things to filter with by setting list, and configure how that list
is processed with the other options.

For example, consider a disk widget showing these entries:

If we wanted to ignoring any entry with a name that matches /dev/sda:

[disk.name_filter]
# Whether to ignore any matches. Defaults to true.
is_list_ignored = true

# A list of filters to try and match.
list = ["/dev/sda"]

# Whether to use regex. Defaults to false.
regex = true

# Whether to be case-sensitive. Defaults to false.
case_sensitive = false

# Whether to require matching the whole word. Defaults to false.
whole_word = false

This would give us:

We can also combine both the name filter and mount filter. For example:

[disk.name_filter]
is_list_ignored = false
list = ["/dev/sda"]
regex = true
case_sensitive = false
whole_word = false

[disk.mount_filter]
is_list_ignored = true
list = ["/mnt/.*", "/"]
regex = true
case_sensitive = false
whole_word = true

This gives us:

Content Configuration Config File Flags (`docs/content/configuration/config-file/flags.md`) Copy Section

Flags

!!! Warning

This section is in progress, and is just copied from the old documentation.

You can configure flags by putting them in [flags] table. Example:

[flags]
hide_avg_cpu = true

Most of the command line flags have config file equivalents to avoid having to type them out
each time:

Content Configuration Config File Layout (`docs/content/configuration/config-file/layout.md`) Copy Section

Layout

!!! Warning

This section is in progress, and is just copied from the old documentation.

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:

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

Furthermore, you can have duplicate widgets.

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

Content Configuration Config File Memory Graph (`docs/content/configuration/config-file/memory-graph.md`) Copy Section

Memory Graph Configuration

If you want to change some of the default behaviour of the memory graph widget, you can configure things under the [memory_graph] (or [memory]) section.

Graph legend position Copy Chapter

You can change where the legend for the graph is placed within the widget itself (or hidden with "none"). The default is "top-right".

[memory_graph]
# One of ["none", "top-left", "top", "top-right", "left", "right", "bottom-left", "bottom", "bottom-right"]
legend_position = "top-left"

Collect/show cache memory Copy Chapter

On Linux, you can change whether the memory used by cache/slabs is collected and
shown. By default, it is false.

[memory_graph]
cache_memory = true

Short GPU names Copy Chapter

If GPU support is enabled, you can use short_gpu_names to display simplified GPU names in the memory graph widget
instead of the full GPU names. If enabled, then if there's only one GPU, it'll just list the entry as GPU;
if there are multiple GPUs, it'll use entries like GPU0, GPU1, etc. By default, this is disabled.

[memory_graph]
short_gpu_names = true

Subtract free-able ARC from memory Copy Chapter

If ZFS is detected (note that the zfs feature must be enabled if built manually), you can enable memory_graph.free_arc to
not count ARC memory in the RAM usage calculations. Disabled
by default.

[memory_graph]
free_arc = true

Content Configuration Config File Network Graph (`docs/content/configuration/config-file/network-graph.md`) Copy Section

Network Graph Configuration

Settings Copy Chapter

If you want to change some of the default behaviour of the network graph widget, you can configure some things in the config file.

Filtering Entries Copy Chapter

You can filter out what entries to show by configuring [network_graph.interface_filter] .
In particular, you can set a list of things to filter with by setting list, and configure how that list is processed with the other options.

For example, here we are ignoring any entry with a name that matches the regex eth0.*, or specifically virbr0.

[network_graph.interface_filter]
# Whether to ignore any matches. Defaults to true.
is_list_ignored = true

# A list of filters to try and match.
list = ["virbr0", "eth0slab"]

# Whether to use regex. Defaults to false.
regex = true

# Whether to be case-sensitive. Defaults to false.
case_sensitive = false

# Whether to require matching the whole word. Defaults to false.
whole_word = false

Content Configuration Config File Processes (`docs/content/configuration/config-file/processes.md`) Copy Section

Processes Configuration

Settings Copy Chapter

If you want to change some of the default behaviour of the processes widget, you can configure some things in the config file.

Columns Copy Chapter

You can configure which columns are shown by the process widget by setting the columns setting:

[processes]
# Pick which columns you want to use in any order.
columns = ["cpu%", "mem%", "pid", "name", "read", "write", "tread", "twrite", "state", "user", "time", "gmem%", "gpu%"]

Default Sort Column Copy Chapter

By default, the process widget starts sorted by CPU usage in descending order. You can change the column it sorts by at startup:

[processes]
default_sort = "mem"

Any of the column names accepted by columns work here (e.g. "cpu%", "mem", "pid", "name", "read"). If the
column you pick is not actually shown by the widget, the built-in default is used instead.

The same setting is also exposed as a CLI flag, which takes precedence over the config file:

btm --process_default_sort mem

You can also set the default order by changing processes.sort_order with "Ascending" or "Descending". If not set, then by default, it will use a sort order that is reasonable (e.g. descending for CPU/memory usage, ascending for process names).

[processes]
sort_order = "Ascending"

Content Configuration Config File Styling (`docs/content/configuration/config-file/styling.md`) Copy Section

Styling

Various parts of the bottom can be styled, using either built-in themes or custom theming.

Precedence Copy Chapter

As there are a few ways styles can be applied to bottom, the order of which styles are prioritized are, in order of
highest precedence to lowest precedence:

1. Built-in themes set via command-line args (e.g. btm --theme gruvbox)
2. Custom themes set via config file
3. Built-in themes set via config file

If nothing is set, it will fall back to the default theme.

Built-in styles Copy Chapter

bottom has a few built-in themes:

• Default
• Nord
• Gruvbox

These themes all also have light variants to support terminals using lighter colours.

To set the theme from the command line:

btm --theme gruvbox

To set the theme using the config file:

[styles]
theme = "gruvbox"

Custom styling Copy Chapter

bottom's components can also be individually styled by the user to control the colour of the text style.

Colours Copy Section

!!! Info

Note that anywhere `"colour"` is used, it can be substituted for `"color"`:

```toml
# This is okay
[styles.widgets.widget_title]
colour = "black"
bg_colour = "white"

[styles.cpu]
all_entry_colour = "green"

# This is also okay
[styles.widgets.widget_title]
color = "black"
bg_color = "white"

[styles.cpu]
all_entry_color = "green"
```

You can configure the colours for components with strings that are either hex colours (e.g. "#ffffff"), RGB colours
(e.g. "255, 255, 255"), or named colours. Named colours are one of the following strings:

• "Black"
• "Red"
• "Green"
• "Yellow"
• "Blue"
• "Magenta"
• "Cyan"
• "Gray"
• "DarkGray"
• "LightRed"
• "LightGreen"
• "LightYellow"
• "LightBlue"
• "LightMagenta"
• "LightCyan"
• "White"

Text Copy Section

Text can generally be styled using the following TOML table:

[field]
# The foreground colour of text.
colour = "black"

# The background colour of text.
bg_colour = "blue"

# Whether to make the text bold.
bold = false

# Inline table version
field = { colour = "black", bg_colour = "blue", bold = false }

All fields are optional; by default if bg_colour is not set then there will be no background colour.

If you just want to style text by setting the foreground colour, for brevity, then you can also just set the field
to be the colour itself. For example:

[styles.widgets]
selected_text = "#fff"

Configuration Copy Section

CPU

These can be set under [styles.cpu]:

Temperature Graph

These can be set under [styles.temp_graph]:

Memory

These can be set under [styles.memory]:

Network

These can be set under [styles.network]:

Battery

These can be set under [styles.battery]:

Tables

These can be set under [styles.tables]:

Graphs

These can be set under [styles.graphs]:

General widget settings

These can be set under [styles.widgets]:

Content Configuration Config File Temperature Graph (`docs/content/configuration/config-file/temperature-graph.md`) Copy Section

Temperature Graph Configuration

The temperature graph widget is configured under [temperature_graph].

Legend Position Copy Chapter

The location of the legend can be set with legend_position. Valid values are none, top-left, top, top-right,
left, right, bottom-left, bottom, and bottom-right. Defaults to top-right.

[temperature_graph]
legend_position = "top-right"

Upper Limit Copy Chapter

By default, the y-axis is bounded at 100°C (or the equivalent in the configured temperature unit) and grows
automatically if a reading exceeds that. An explicit upper bound can be set with max_temp (uses the same unit as
the configured temperature unit). Sensor readings above this value will be drawn off the chart.

[temperature_graph]
max_temp = 90.0

Filtering Entries Copy Chapter

You can filter which sensors to plot by configuring [temperature_graph.sensor_filter]. This works the same way as
the temperature table's filter.

For example, here we are ignoring any sensor that has "cpu" or "wifi" in its name:

[temperature_graph.sensor_filter]
# Whether to ignore any matches. Defaults to true.
is_list_ignored = true

# A list of filters to try and match.
list = ["cpu", "wifi"]

# Whether to use regex. Defaults to false.
regex = false

# Whether to be case-sensitive. Defaults to false.
case_sensitive = false

# Whether to require matching the whole word. Defaults to false.
whole_word = false

Content Configuration Config File Temperature Table (`docs/content/configuration/config-file/temperature-table.md`) Copy Section

Temperature Table Configuration

The temperature table widget is configured under [temperature].

Default Sort Column Copy Chapter

You can customize the default sort column (by default, it sorts by temperature sensor name in ascending order). For example, to sort by temperature:

[temperature]
default_sort = "Temp"

You can also set the sort order by changing temperature.sort_order with "Ascending" or "Descending". Defaults to
"Ascending":

[temperature]
sort_order = "Ascending"

Filtering Entries Copy Chapter

You can filter out what entries to show by configuring [temperature.sensor_filter]. In particular you can set a list of things to filter with by setting list, and configure how that list is processed with the other options.

For example, here we are ignoring any sensor that has "cpu" or "wifi" in it.

[temperature.sensor_filter]
# Whether to ignore any matches. Defaults to true.
is_list_ignored = true

# A list of filters to try and match.
list = ["cpu", "wifi"]

# Whether to use regex. Defaults to false.
regex = false

# Whether to be case-sensitive. Defaults to false.
case_sensitive = false

# Whether to require matching the whole word. Defaults to false.
whole_word = false

Content Contribution Development Build Process (`docs/content/contribution/development/build_process.md`) Copy Section

Build Process

!!! Warning

This section is currently somewhat WIP.

!!! Warning

This section is intended for people who wish to work on/build/distribute bottom, not general users.

Overview Copy Chapter

bottom manages its own binary builds for nightly and stable release purposes. The core build workflow is handled by build_releases.yml, called by a wrapper workflow for nightly and stable releases. Builds take place via GitHub Actions.

The main things built are:

• Binaries for various platforms
• MSI installer for Windows
• .deb package for Debian and its derivatives

This documentation gives a high-level overview of the build process for each part. For the most up-to-date and detailed reference, definitely refer back to the build_releases.yml file.

Binaries Copy Chapter

Binaries are built currently for various targets. Note that not all of these are officially supported. The following general steps are performed:

• Set up the Rust toolchain for the action runner.

• Enable cache.

• Build a release build with:

  • --features deploy, which enables only crates needed for release builds.

  • --locked to lock the dependency versions.

  • The following env variables set:

    • BTM_GENERATE: true
    • COMPLETION_DIR: "target/tmp/bottom/completion/"
    • MANPAGE_DIR: "target/tmp/bottom/manpage/"

    These generate the manpages and shell completions (see Packaging for some more information).

• Bundle the binaries and manpage/completions.

• Cleanup.

Some builds use cross to do cross-compilation builds for architectures otherwise not natively supported by the runner.

MSI Copy Chapter

This builds a full Windows installer using cargo-wix and WiX Toolset 4.
This requires some setup beforehand with some dependencies:

• Net-Framework-Core (handled by Powershell)
• WiX Toolset 4 (needs to be separately installed on GitHub runners as a .NET tool)
• Rust toolchain

After that, cargo wix takes care of the rest.

`.deb` Copy Chapter

Currently, .deb files are built for x86 and ARM architectures (armv7, aarch64). This is handled by cargo-deb.

• For x86, this is handled natively with just cargo-deb.
• For ARM, this uses a Docker container, cargo-deb-arm, which correctly sets the dependencies and architecture for the generated .deb file.

There are additional checks via dpkg to ensure the architecture is correctly set.

Content Contribution Development Deploy Process (`docs/content/contribution/development/deploy_process.md`) Copy Section

Deploy Process

!!! Warning

This section is currently WIP.

!!! Warning

This section is intended for people who wish to work on/build/distribute bottom, not general users.

Overview Copy Chapter

bottom currently has two main deploy processes to worry about:

• Nightly: a daily (00:00 UTC) GitHub action to build binary/installer files, and upload them to the nightly release (example). It can also be triggered manually as either a proper nightly release or a mock release.

• Stable: a stable deployment, triggered manually or upon creation of a valid tag. This is a GitHub action that builds binary/installer files and uploads them to a new GitHub release.

  Furthermore, this workflow does not handle the following deployments, which must be manually handled:

  • Chocolatey
  • crates.io

Nightly Copy Chapter

This is, for the most part, automatic, though it can also be used as a way of testing build workflow changes and seeing if binaries can be successfully built at all against all the targets we want to build for.

If one does not want to actually update the nightly release, and just want to test the general builds and workflow, one can run the workflow manually on a branch of choice with "mock" set as the parameter. Changing it to anything else will trigger a non-mock run.

Stable Copy Chapter

This can be manually triggered, though the general use-case is setting a tag of the form x.y.z (after checking everything is good, of course). For example:

git tag 0.6.9 && git push origin 0.6.9

This will automatically trigger the deployment workflow, and create a draft release with the files uploaded. One still needs to fill in the details and release it.

Furthermore, there are some deployments that are handled by maintainers of bottom that this workflow does not automatically finish. These must be manually handled.

crates.io Copy Section

Validate everything builds properly and works (you should have done this before releasing though). If good, then deploying on crates.io is as simple as:

cargo publish

Chocolatey Copy Section

Upon releasing on GitHub, choco-bottom will automatically be updated with a new PR with the correct deployment files for Chocolatey. Check the PR, merge it if it is correct, then pull locally and deploy following the instructions in the README. Make sure to test installation and running at least once before deploying!

If done correctly, there should be a new build on Chocolatey, which will take some time to validate.

winget Copy Section

Sometimes, people will kindly do it, but it can also be manually triggered using
winget-bottom.

Note this requires regenerating some secrets.

Content Contribution Development Dev Env (`docs/content/contribution/development/dev_env.md`) Copy Section

Development Environment

!!! Warning

This section is currently WIP.

!!! Warning

This section is intended for people who wish to work on/build/distribute bottom, not general users.

Content Contribution Development Logging (`docs/content/contribution/development/logging.md`) Copy Section

Logging

!!! Warning

This section is currently WIP.

!!! Warning

This section is intended for people who wish to work on/build/distribute bottom, not general users.

Content Contribution Development Testing (`docs/content/contribution/development/testing.md`) Copy Section

Testing

!!! Warning

This section is currently WIP.

!!! Warning

This section is intended for people who wish to work on/build/distribute bottom, not general users.

Content Usage Widgets Battery (`docs/content/usage/widgets/battery.md`) Copy Section

Battery Widget

!!! Warning

The battery features are unavailable if the binary is compiled with the `battery` feature disabled or if there are no batteries on the system!

The battery widget provides information about batteries on the system.

The battery widget can be enabled through either the --battery flag, the battery = true option in a config file, or specifying the widget in a custom layout.

Features Copy Chapter

The following data is displayed for batteries:

• Charge percent
• Consumption rate
• Charging state
• Time to empty/charge, based on the current state
• Battery health percent

The battery widget also supports devices with multiple batteries, and you can switch between them using the keyboard or the mouse.

Key bindings Copy Chapter

Note that key bindings are generally case-sensitive.

Mouse bindings Copy Chapter

Content Usage Widgets Cpu Graph (`docs/content/usage/widgets/cpu-graph.md`) Copy Section

CPU Widget

The CPU widget displays a visual representation of CPU usage over a time range.

Features Copy Chapter

The CPU widget is composed of two parts: the graph and the legend:

• The graph displays the usage data for the currently selected entry as a percentage
• The legend displays all available entries that can be displayed on the graph along with their last recorded use percentage (except for the "All" option)

Users can scroll through the legend using either the keyboard or mouse to select which entry to display on the graph. The "All" option shows every entry
at the same time, though this may get a bit hard to follow if you have a large number of cores/threads.

One can also adjust the displayed time range through either the keyboard or mouse, with a range of 30s to 600s.

Key bindings Copy Chapter

Note that key bindings are generally case-sensitive.

Graph Copy Section

Legend Copy Section

Mouse bindings Copy Chapter

Graph Copy Section

Legend Copy Section

Content Usage Widgets Disk Io Graph (`docs/content/usage/widgets/disk-io-graph.md`) Copy Section

Disk I/O Graph Widget

The disk I/O graph widget shows read and write rates over time.

Features Copy Chapter

The legend displays the current reads and writes per second in bytes for each mount/disk item. The y-axis
automatically scales based on shown read/write values. By default this is in a linear scale, but it can be
switched to a logarithmic scale through the config file.

The displayed time range can be adjusted through either the keyboard or mouse.

Key bindings Copy Chapter

Note that key bindings are generally case-sensitive.

Mouse bindings Copy Chapter

Content Usage Widgets Disk (`docs/content/usage/widgets/disk.md`) Copy Section

Disk Widget

The disk widget provides a table of useful disk and partition information, like I/O per second and total usage.

Features Copy Chapter

The disk widget provides the following information:

• Disk name
• Disk mount location
• Amount of space used
• Amount of space left
• Total amount of space
• Percentage of space used
• Read per second
• Write per second

Key bindings Copy Chapter

Note that key bindings are generally case-sensitive.

Mouse bindings Copy Chapter

Content Usage Widgets Memory Graph (`docs/content/usage/widgets/memory-graph.md`) Copy Section

Memory Widget

The memory widget provides a visual representation of RAM and swap usage over time.

Features Copy Chapter

The legend displays the current usage in terms of percentage and actual usage in binary units (KiB, MiB, GiB, etc.).
If the total RAM or swap available is 0, then it is automatically hidden from the legend and graph.

One can also adjust the displayed time range through either the keyboard or mouse, with a range of 30s to 600s.

This widget can also be configured to display Nvidia and AMD GPU memory usage (--disable_gpu on Linux/Windows to disable) or cache memory usage (--enable_cache_memory).

Key bindings Copy Chapter

Note that key bindings are generally case-sensitive.

Mouse bindings Copy Chapter

How are memory values determined? Copy Chapter

Linux Copy Section

Memory usage is calculated using the following formula based on values from /proc/meminfo (based on htop's implementation):

MemTotal - MemFree - Buffers - (Cached + SReclaimable - Shmem)

You can find more info on /proc/meminfo and its fields here.

Windows Copy Section

In Windows, we calculate swap by querying Get-Counter "\Paging File(*)\% Usage". This
is also what some libraries like psutil use. However, note there are also a few other valid methods of
representing "swap" in Windows (e.g. using GetPerformanceInfo), which all slightly don't
match.

Content Usage Widgets Network Graph (`docs/content/usage/widgets/network-graph.md`) Copy Section

Network Widget

The network widget provides a visual representation of network input and output per second, as well as noting the total amount
received and transmitted.

Features Copy Chapter

The legend displays the current reads and writes per second in bits, as well as the total amount read/written.

The y-axis automatically scales based on shown read/write values, and by default, is a linear scale based on base-10 units (e.x. kilobit, gigabit, etc.).
Through configuration, the read/write per second unit can be changed to bytes, while the y-axis can be changed to a
log scale and/or use base-2 units (e.x. kibibit, gibibit, etc.).

One can also adjust the displayed time range through either the keyboard or mouse, with a range of 30s to 600s.

Key bindings Copy Chapter

Note that key bindings are generally case-sensitive.

Mouse bindings Copy Chapter

Content Usage Widgets Process (`docs/content/usage/widgets/process.md`) Copy Section

Process Widget

The process widget displays a table containing information regarding a running process, along with sorting,
searching, and process control features.

Features Copy Chapter

The process widget has three main components:

• The main process table
• The search sub-widget (opened with ++ctrl+f++ or ++slash++)
• The sort menu sub-widget (opened with ++s++ or ++f6++)

By default, the main process table displays the following information for each process:

• PID

• Name of the process

• CPU use percentage (note this is averaged out per available thread by default)

• Memory use percentage

• Disk reads per second

• Disk writes per second

• Total amount read from disk

• Total amount written from disk

• User

• Process state

• Process uptime

  !!! info indent

  text Copy

  On Windows, the I/O counters will report _all_ reads/writes, not just disk. See
  [here](https://docs.rs/sysinfo/latest/sysinfo/struct.Process.html#method.disk_usage)
  for more details.

With the feature flag (--disable_gpu on Linux/Windows to disable) and gpu process columns enabled in the configuration:

• GPU memory use percentage
• GPU core utilization percentage

See the processes configuration page on how to customize which columns
are shown.

Sorting Copy Section

The table can be sorted by clicking on the table headers, which will either sort the table by that column, or if already
sorting by that column, reverse the sorting order.

Alternatively, one can sort using the sort menu sub-widget, which is brought up using ++s++ or ++f6++, and can be controlled by arrow keys or the mouse.

Grouping Copy Section

Pressing ++tab++ in the table will group entries with the same name together. The PID column will be replaced with the number of entries in each group, and usage
is added together when displayed.

!!! Info

Note that the process state and user columns are disabled in this mode.

!!! Info

Note that if tree mode is also active, processes cannot be grouped together due to the behaviour of the two modes
somewhat clashing. This also reflects with default modes like `group_processes`.

Process termination Copy Section

Pressing ++d+d++ or ++f9++ will allow you to terminate the currently selected process/process group. On Unix-like
operating systems, you are also able to control which specific signals to send (e.g. SIGKILL, SIGTERM).

<figcaption><sub>The process termination menu on Linux</sub></figcaption>

If you're on Windows, or if the disable_advanced_kill flag is set in the options or command-line (only available on
Linux, macOS, and FreeBSD), then a simpler termination screen with just yes or no options will be shown.

<figcaption><sub>The process termination menu on Windows</sub></figcaption>

Tree mode Copy Section

Pressing ++t++ or ++f5++ in the table toggles tree mode in the process widget, displaying processes in regard to their parent-child process relationships.

A process in tree mode can also be "collapsed", hiding its children and any descendants, using the either the ++minus++,
++plus++, or ++left++ keys, or clicking on an entry. It can be expanded by using the ++minus++, ++plus++, or ++right++
keys, or by clicking on the entry again. The ++space++ key can also be used to toggle between the collapsed and expanded states.

!!! Info

Note that if tree mode is active, processes cannot be grouped together due to the behaviour of the two modes
somewhat clashing. This also reflects with default modes like `group_processes`.

Full command Copy Section

You can show the full command instead of just the process name by pressing ++P++.

Search Copy Section

Pressing ++slash++ or ++ctrl+f++ will open up the search sub-widget. By default, just typing in something will search by the process name.

This search can be further enhanced by matching by case, matching the entire word, or by regex.

We are able to also search for multiple things/conditions.

And if our search uses a keyword, we need to use quotation marks around the term to properly search it.

Lastly, we can refine our search even further based on the other columns, like PID, CPU usage, etc., as well as grouping together conditions.

You can also paste search queries (e.g. ++shift+insert++, ++ctrl+shift+v++).

Keywords

Note all keywords are case-insensitive. To search for a process/command that collides with a keyword, surround the term with quotes (e.x. "cpu").

Comparison operators

Logical operators

Note all operators are case-insensitive, and the and operator takes precedence over the or operator.

! is reserved as an operator, so it cannot appear bare as a value. To match a literal ! in a name or string field, quote it — e.g. "foo!" or user = "!". A bare ! with nothing parseable after it (such as user = ! or ! on its own) is rejected.

Units

All units are case-insensitive.

Key bindings Copy Chapter

Note that key bindings are generally case-sensitive.

Process table Copy Section

Sort sub-widget Copy Section

Search sub-widget Copy Section

Mouse bindings Copy Chapter

Process table Copy Section

Sort sub-widget Copy Section

Content Usage Widgets Temperature Graph (`docs/content/usage/widgets/temperature-graph.md`) Copy Section

Temperature Graph Widget

The temperature graph widget provides temperature readings over time.

Features Copy Chapter

Each detected sensor is drawn as its own line. The y-axis is in the configured temperature unit (Celsius by default;
see the --celsius/--fahrenheit/--kelvin arguments or flags.temperature_type config option).

By default the y-axis is bounded at 100°C (or the equivalent in the configured unit) and grows automatically.
An upper bound can also be set explicitly via the config file.

The displayed time range can be adjusted through either the keyboard or mouse.

Key bindings Copy Chapter

Note that key bindings are generally case-sensitive.

Mouse bindings Copy Chapter

Content Usage Widgets Temperature Table (`docs/content/usage/widgets/temperature-table.md`) Copy Section

Temperature Widget

The temperature widget provides a table of temperature sensors and their current temperature.

Features Copy Chapter

The temperature widget provides the sensor name as well as its current temperature.

This widget can also be configured to display Nvidia and AMD GPU temperatures (--disable_gpu on Linux/Windows to disable).

Key bindings Copy Chapter

Note that key bindings are generally case-sensitive.

Mouse bindings Copy Chapter

--- METRICS ---

• Files Extracted: 44
• Estimated Token Budget: ~45337 tokens
• Canonical Reference: https://codewiki.google/github.com/ClementTsang/bottom