path: root/README.md

# ![btop++](Img/logo.png)

<a href="https://repology.org/project/btop/versions">
    <img src="https://repology.org/badge/vertical-allrepos/btop.svg" alt="Packaging status" align="right">
</a>

![Linux](https://img.shields.io/badge/-Linux-grey?logo=linux)
![macOS](https://img.shields.io/badge/-OSX-black?logo=apple)
![FreeBSD](https://img.shields.io/badge/-FreeBSD-red?logo=freebsd)
![Usage](https://img.shields.io/badge/Usage-System%20resource%20monitor-yellow)
![c++20](https://img.shields.io/badge/cpp-c%2B%2B20-green)
![latest_release](https://img.shields.io/github/v/tag/aristocratos/btop?label=release)
[![Donate](https://img.shields.io/badge/-Donate-yellow?logo=paypal)](https://paypal.me/aristocratos)
[![Sponsor](https://img.shields.io/badge/-Sponsor-red?logo=github)](https://github.com/sponsors/aristocratos)
[![Coffee](https://img.shields.io/badge/-Buy%20me%20a%20Coffee-grey?logo=Ko-fi)](https://ko-fi.com/aristocratos)
[![btop](https://snapcraft.io/btop/badge.svg)](https://snapcraft.io/btop)
[![Continuous Build Linux](https://github.com/aristocratos/btop/actions/workflows/continuous-build-linux.yml/badge.svg)](https://github.com/aristocratos/btop/actions/workflows/continuous-build-linux.yml)
[![Continuous Build macOS](https://github.com/aristocratos/btop/actions/workflows/continuous-build-macos.yml/badge.svg)](https://github.com/aristocratos/btop/actions/workflows/continuous-build-macos.yml)
[![Continuous Build FreeBSD](https://github.com/aristocratos/btop/actions/workflows/continuous-build-freebsd.yml/badge.svg)](https://github.com/aristocratos/btop/actions/workflows/continuous-build-freebsd.yml)

## Index

* [News](#news)
* [Documents](#documents)
* [Description](#description)
* [Features](#features)
* [Themes](#themes)
* [Support and funding](#support-and-funding)
* [Prerequisites](#prerequisites) (Read this if you are having issues!)
* [Screenshots](#screenshots)
* [Keybindings](#help-menu)
* [Installation Linux/macOS](#installation)
* [Compilation Linux](#compilation-linux)
* [Compilation macOS](#compilation-macos-osx)
* [Compilation FreeBSD](#compilation-freebsd)
* [Installing the snap](#installing-the-snap)
* [Configurability](#configurability)
* [License](#license)

## News

##### 28 August 2022

[![btop4win](https://github.com/aristocratos/btop4win/raw/master/Img/logo.png)](https://github.com/aristocratos/btop4win)

First release of btop4win available at https://github.com/aristocratos/btop4win

##### 16 January 2022

Release v1.2.0 with FreeBSD support. No release binaries for FreeBSD provided as of yet.

Again a big thanks to [@joske](https://github.com/joske) for his porting efforts!

Since compatibility with Linux, macOS and FreeBSD are done, the focus going forward will be on new features like GPU monitoring.

##### 13 November 2021

Release v1.1.0 with macOS support. Binaries in [continuous-build-macos](https://github.com/aristocratos/btop/actions/workflows/continuous-build-macos.yml) are only x86 for now.
macOS binaries + installer are included for both x86 and ARM64 (Apple Silicon) in the releases.

Big thank you to [@joske](https://github.com/joske) who wrote the vast majority of the implementation!

<details>
<summary>More...</summary>

##### 30 October 2021

Work on the OSX [macOS] and FreeBSD branches, both initiated and mostly worked on by [@joske](https://github.com/joske), will likely be completed in the coming weeks.
The OSX [macOS] branch has some memory leaks that needs to be sorted out and both have some issues with the processes cpu usage calculation and other smaller issues that needs fixing.

If you want to help out, test for bugs/fix bugs or just try out the branches:

**macOS / OSX**
```bash
# Install and use Homebrew or MacPorts package managers for easy dependency installation
brew install coreutils make gcc@11
git clone https://github.com/aristocratos/btop.git
cd btop
git checkout OSX
gmake
```

**FreeBSD**
```bash
sudo pkg install gmake gcc11 coreutils git
git clone https://github.com/aristocratos/btop.git
cd btop
git checkout freebsd
gmake
```

Note that GNU make (`gmake`) is recommended but not required for macOS/OSX but it is required on FreeBSD.


##### 6 October 2021

macOS development have been started by [@joske](https://github.com/joske), big thanks :)
See branch [OSX](https://github.com/aristocratos/btop/tree/OSX) for current progress.

##### 18 September 2021

The Linux version of btop++ is complete. Released as version 1.0.0

I will be providing statically compiled binaries for a range of architectures in every release for those having problems compiling.

For compilation GCC 10 is required, GCC 11 preferred.

Please report any bugs to the [Issues](https://github.com/aristocratos/btop/issues/new?assignees=aristocratos&labels=bug&template=bug_report.md&title=%5BBUG%5D) page.

The development plan right now:

* 1.1.0 macOS [OSX] support
* 1.2.0 FreeBSD support
* 1.3.0 Support for GPU monitoring
* 1.X.0 Other platforms and features...

Windows support is not in the plans as of now, but if anyone else wants to take it on, I will try to help.

##### 5 May 2021

This project is gonna take some time until it has complete feature parity with bpytop, since all system information gathering will have to be written from scratch without any external libraries.
And will need some help in the form of code contributions to get complete support for BSD and macOS/OSX.

</details>

## Documents

**[CHANGELOG.md](CHANGELOG.md)**

**[CONTRIBUTING.md](CONTRIBUTING.md)**

**[CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)**

## Description

Resource monitor that shows usage and stats for processor, memory, disks, network and processes.

C++ version and continuation of [bashtop](https://github.com/aristocratos/bashtop) and [bpytop](https://github.com/aristocratos/bpytop).

## Features

* Easy to use, with a game inspired menu system.
* Full mouse support, all buttons with a highlighted key is clickable and mouse scroll works in process list and menu boxes.
* Fast and responsive UI with UP, DOWN keys process selection.
* Function for showing detailed stats for selected process.
* Ability to filter processes.
* Easy switching between sorting options.
* Tree view of processes.
* Send any signal to selected process.
* UI menu for changing all config file options.
* Auto scaling graph for network usage.
* Shows IO activity and speeds for disks.
* Battery meter
* Selectable symbols for the graphs.
* Custom presets
* And more...

## Themes

Btop++ uses the same theme files as bpytop and bashtop (some color values missing in bashtop themes) .

See [themes](https://github.com/aristocratos/btop/tree/master/themes) folder for available themes.

The `make install` command places the default themes in `[$PREFIX or /usr/local]/share/btop/themes`.
User created themes should be placed in `$XDG_CONFIG_HOME/btop/themes` or `$HOME/.config/btop/themes`.

Let me know if you want to contribute with new themes.

## Support and funding

You can sponsor this project through github, see [my sponsors page](https://github.com/sponsors/aristocratos) for options.

Or donate through [paypal](https://paypal.me/aristocratos) or [ko-fi](https://ko-fi.com/aristocratos).

Any support is greatly appreciated!

## Prerequisites

For best experience, a terminal with support for:

* 24-bit truecolor ([See list of terminals with truecolor support](https://github.com//termstandard/colors))
* 256-color terminals are supported through 24-bit to 256-color conversion when setting "truecolor" to False in the options or with "-lc/--low-color" arguments.
* 16 color TTY mode will be activated if a real tty device is detected. Can be forced with "-t/--tty_on" arguments.
* Wide characters (Are sometimes problematic in web-based terminals)

Also needs a UTF8 locale and a font that covers:

* Unicode Block “Braille Patterns” U+2800 - U+28FF (Not needed in TTY mode or with graphs set to type: block or tty.)
* Unicode Block “Geometric Shapes” U+25A0 - U+25FF
* Unicode Block "Box Drawing" and "Block Elements" U+2500 - U+259F

### **Notice (Text rendering issues)**

* If you are having problems with the characters in the graphs not looking like they do in the screenshots, it's likely a problem with your systems configured fallback font not having support for braille characters.

* See [Terminess Powerline](https://github.com/ryanoasis/nerd-fonts/tree/master/patched-fonts/Terminus/terminus-ttf-4.40.1) for an example of a font that includes the braille symbols.

* See comments by @sgleizes [link](https://github.com/aristocratos/bpytop/issues/100#issuecomment-684036827) and @XenHat [link](https://github.com/aristocratos/bpytop/issues/100#issuecomment-691585587) in issue #100 for possible solutions.

* If text are misaligned and you are using Konsole or Yakuake, turning off "Bi-Directional text rendering" is a possible fix.

* Characters clipping in to each other or text/border misalignments is not bugs caused by btop, but most likely a fontconfig or terminal problem where the braille characters making up the graphs aren't rendered correctly.

* Look to the creators of the terminal emulator you use to fix these issues if the previous mentioned fixes don't work for you.

## Screenshots

#### Main UI showing details for a selected process

![Screenshot 1](Img/normal.png)

#### Main UI in TTY mode

![Screenshot 2](Img/tty.png)

#### Main UI with custom options

![Screenshot 3](Img/alt.png)

#### Main-menu

![Screenshot 3](Img/main-menu.png)

#### Options-menu

![Screenshot 4](Img/options-menu.png)

#### Help-menu

![Screenshot 5](Img/help-menu.png)

## Installation

**Binaries for Linux are statically compiled with musl and works on kernel 2.6.39 and newer**

1. **Download btop-(VERSION)-(ARCH)-(PLATFORM).tbz from [latest release](https://github.com/aristocratos/btop/releases/latest) and unpack to a new folder**

   **Notice! Use x86_64 for 64-bit x86 systems, i486 and i686 are 32-bit!**

2. **Install (from created folder)**

   * **Run install.sh or:**

   ``` bash
   # use "make install PREFIX=/target/dir" to set target, default: /usr/local
   # only use "sudo" when installing to a NON user owned directory
   sudo make install
   ```

3. **(Optional) Set suid bit to make btop always run as root (or other user)**

   Enables signal sending to any process without starting with `sudo` and can prevent /proc read permissions problems on some systems.

   * **Run setuid.sh or:**

   ``` bash
   # run after make install and use same PREFIX if any was used at install
   # set SU_USER and SU_GROUP to select user and group, default is root:root
   sudo make setuid
   ```

* **Uninstall**

  * **Run uninstall.sh or:**

   ``` bash
   sudo make uninstall
   ```

* **Show help**

   ```bash
   make help
   ```

**Binary release (from native os repo)**

* **openSUSE**
  * **Tumbleweed:**
    ```bash
    sudo zypper in btop
    ```
  * For all other versions, see [openSUSE Software: btop](https://software.opensuse.org/package/btop)
* **Fedora**
    ```bash
    sudo dnf install btop
	```
* **RHEL/AlmaLinux 8+**
    ```bash
    sudo dnf install epel-release
	sudo dnf install btop
	```
* **FreeBSD**
	```sh
	pkg install btop
	```


**Binary release on Homebrew (macOS (x86_64 & ARM64) / Linux (x86_64))**

* **[Homebrew](https://formulae.brew.sh/formula/btop)**
  ```bash
  brew install btop
  ```

## Compilation Linux

   Needs GCC 10 or higher, (GCC 11 or above strongly recommended for better CPU efficiency in the compiled binary).

   The makefile also needs GNU coreutils and `sed` (should already be installed on any modern distribution).

   For a `cmake` based build alternative see the [fork](https://github.com/jan-guenter/btop/tree/main) by @jan-guenter

1. **Install dependencies (example for Ubuntu 21.04 Hirsute)**

   Use gcc-10 g++-10 if gcc-11 isn't available

   ``` bash
   sudo apt install coreutils sed git build-essential gcc-11 g++-11
   ```

2. **Clone repository**

   ``` bash
   git clone https://github.com/aristocratos/btop.git
   cd btop
   ```

3. **Compile**

   Append `VERBOSE=true` to display full compiler/linker commands.

   Append `STATIC=true` for static compilation.

   Notice! If using LDAP Authentication, usernames will show as UID number for LDAP users if compiling statically with glibc.

   Append `QUIET=true` for less verbose output.

   Append `STRIP=true` to force stripping of debug symbols (adds `-s` linker flag).

   Append `ARCH=<architecture>` to manually set the target architecture.
   If omitted the makefile uses the machine triple (output of `-dumpmachine` compiler parameter) to detect the target system.

   Use `ADDFLAGS` variable for appending flags to both compiler and linker.

   For example: `ADDFLAGS=-march=native` might give a performance boost if compiling only for your own system.

   If `g++` is linked to an older version of gcc on your system specify the correct version by appending `CXX=g++-10` or `CXX=g++-11`.

   ``` bash
   make
   ```

4. **Install**

   Append `PREFIX=/target/dir` to set target, default: `/usr/local`

   Notice! Only use "sudo" when installing to a NON user owned directory.

   ``` bash
   sudo make install
   ```

5. **(Optional) Set suid bit to make btop always run as root (or other user)**

   No need for `sudo` to enable signal sending to any process and to prevent /proc read permissions problems on some systems.

   Run after make install and use same PREFIX if any was used at install.

   Set `SU_USER` and `SU_GROUP` to select user and group, default is `root` and `root`

   ``` bash
   sudo make setuid
   ```

* **Uninstall**

   ``` bash
   sudo make uninstall
   ```

* **Remove any object files from source dir**

   ```bash
   make clean
   ```

* **Remove all object files, binaries and created directories in source dir**

   ```bash
   make distclean
   ```

* **Show help**

   ```bash
   make help
   ```

## Compilation macOS OSX

   Needs GCC 10 or higher, (GCC 11 or above strongly recommended for better CPU efficiency in the compiled binary).
   
   GCC 12 needed for macOS Ventura. If you get linker errors on Ventura you'll need to upgrade your command line tools (Version 14.0) is bugged.

   The makefile also needs GNU coreutils and `sed`.

   Install and use Homebrew or MacPorts package managers for easy dependency installation

1. **Install dependencies (example for Homebrew)**

   ``` bash
   brew install coreutils make gcc@12
   ```

2. **Clone repository**

   ``` bash
   git clone https://github.com/aristocratos/btop.git
   cd btop
   ```

3. **Compile**

   Append `VERBOSE=true` to display full compiler/linker commands.
   
   Append `STATIC=true` for static compilation (only libgcc and libstdc++ will be static!).

   Append `QUIET=true` for less verbose output.

   Append `STRIP=true` to force stripping of debug symbols (adds `-s` linker flag).

   Append `ARCH=<architecture>` to manually set the target architecture.
   If omitted the makefile uses the machine triple (output of `-dumpmachine` compiler parameter) to detect the target system.

   Use `ADDFLAGS` variable for appending flags to both compiler and linker.

   For example: `ADDFLAGS=-march=native` might give a performance boost if compiling only for your own system.

   ``` bash
   gmake
   ```

4. **Install**

   Append `PREFIX=/target/dir` to set target, default: `/usr/local`

   Notice! Only use "sudo" when installing to a NON user owned directory.

   ``` bash
   sudo gmake install
   ```

5. **(Recommended) Set suid bit to make btop always run as root (or other user)**

   No need for `sudo` to see information for non user owned processes and to enable signal sending to any process.

   Run after make install and use same PREFIX if any was used at install.

   Set `SU_USER` and `SU_GROUP` to select user and group, default is `root` and `wheel`

   ``` bash
   sudo gmake setuid
   ```

* **Uninstall**

   ``` bash
   sudo gmake uninstall
   ```

* **Remove any object files from source dir**

   ```bash
   gmake clean
   ```

* **Remove all object files, binaries and created directories in source dir**

   ```bash
   gmake distclean
   ```

* **Show help**

   ```bash
   gmake help
   ```

## Compilation FreeBSD

   Needs GCC 10 or higher, (GCC 11 or above strongly recommended for better CPU efficiency in the compiled binary).

   Note that GNU make (`gmake`) is required to compile on FreeBSD.

1. **Install dependencies**

   ``` bash
   sudo pkg install gmake gcc11 coreutils git
   ```

2. **Clone repository**

   ``` bash
   git clone https://github.com/aristocratos/btop.git
   cd btop
   ```

3. **Compile**

   Append `VERBOSE=true` to display full compiler/linker commands.

   Append `QUIET=true` for less verbose output.

   Append `STRIP=true` to force stripping of debug symbols (adds `-s` linker flag).

   Append `ARCH=<architecture>` to manually set the target architecture.
   If