# Settings and config file

Canonical: https://plottypus.com/docs/settings

Last updated: 2026-09-23

> The settings page, where config.toml lives, every key with its default, and how plottypus saves without touching your comments.

## The settings page

`s` (or Settings in the `plottypus ≡` menu) opens settings. It replaces the dashboard entirely rather than floating over it; sampling carries on underneath.

```text
 plottypus › settings                                                     esc close

 ▌ general   │ ▌ sample every    ‹ 500 ms ›
   appearance│   layout            auto
   panels    │   network units     bytes/s
   processes │   battery saver     auto
   keys      │   preset            custom
   about     │

               How often plottypus samples. Faster is smoother; slower uses less power.

 ↑↓ move  ←→ change  tab section  / search  esc close
```

- `↑` `↓` or `j` `k` move; `←` `→`, `h` `l`, `enter` or `space` change the value; `tab` switches section.
- `/` searches every section by name or description. `esc` clears the search; a second `esc` closes.
- Click a section, click a value to cycle it, scroll to move.
- **appearance** previews every theme with its own colours; click one to use it. **about** shows the version, the config path and your licence tier.

Changes apply at once and are saved a second later.

## Where the file lives

```text
$XDG_CONFIG_HOME/plottypus/config.toml
~/.config/plottypus/config.toml          # when XDG_CONFIG_HOME is not set
```

`--config <path>` reads a different file for one run. The file does not exist until you change something.

## How it is saved

- **Only when you change something**, one second after the last change, and again on quit or on `HUP`, `TERM` or `INT`.
- **Only the keys you changed.** Your comments, your ordering and keys plottypus does not know are left exactly as they were.
- **Atomically**: a temporary file, then a rename, so a crash never leaves half a file. If `config.toml` is a symlink (a dotfiles repo, say), the write goes to its target and the link survives.
- A **read-only** file is never written. The footer says `config is read-only (not saved)` once and the session carries on.
- A file that **does not parse** is copied to `config.toml.bak`, left alone, and the session runs on defaults.
- A value of the wrong type or out of range falls back to its default on its own and is named in the footer; the rest of the file still applies.

## Every key

The defaults, as a complete file:

```toml
version = 1
interval_ms = 500        # 250, 500, 1000, 2000 or 5000
surface = "auto"         # auto | work | glance
theme = "auto"           # auto or a theme name
icons = "auto"           # auto | unicode | nerd | none
keymap = "default"       # default (same as plottypus) | htop | btop
low_power = "auto"       # auto | on | off
zen = false              # hide the footer and the scale labels
glass = "auto"           # auto | on | off: clear backgrounds for see-through windows
extra_contrast = false

[panels]
gpu = true
net = true
disk = false
fans = true              # the heat box: fans and temperatures
power = true             # battery, or system watts on a desktop
cores = true             # per-core bars in the cpu box

[proc]
tree = false
threads = false          # add a thread-count column
ratio = 55               # process pane width, % (35 to 72); dragging the split saves it
cpu_unit = "core"        # core (100% = one core) | total (100% = the whole chip)

[proc.sort]
column = "cpu"           # cpu | mem | pid | name | user | state | gpu | rss | threads
                         # | power | read | write | wakeups | started
desc = true              # biggest first

[units]
net_bits = false         # true: network in bits/s instead of bytes/s
```

| Key | Settings page | What it does |
| --- | --- | --- |
| `interval_ms` | general → sample every | How often plottypus samples. `[` and `]` step it live. |
| `surface` | general → layout | `work` or `glance` at start; `auto` picks by window size. |
| `units.net_bits` | general → network units | Bytes per second (like Finder) or bits per second (like your ISP). |
| `low_power` | general → battery saver | Saved, but has no effect in 1.0.0: sampling does not slow down on battery yet. |
| — | general → preset | Applies one of the five presets; `custom` when your settings match none. |
| `theme` | appearance → theme | See [Themes and glass](https://plottypus.com/docs/themes). |
| `icons` | appearance → icons | Glyphs beside each box title. `nerd` needs a Nerd Font; `none` is plain ASCII. |
| `glass` | appearance → glass | For translucent windows: no cell backgrounds, brighter frames. |
| `extra_contrast` | appearance → extra contrast | Brighter dim text, hints and frames over a busy wallpaper. |
| `zen` | appearance → zen mode | Graphs only. `Z` toggles it. |
| `panels.*` | panels | Show or hide each box. A box for hardware your Mac lacks stays hidden either way. |
| `proc.sort.column`, `proc.sort.desc` | processes → sort by, biggest first | The process order. Clicking a header does the same. |
| `proc.tree` | processes → tree view | Nest each process under its parent. |
| `proc.threads` | processes → threads column | Add a thread-count column. |
| `proc.cpu_unit` | processes → cpu percent | `core`: 100% is one core. `total`: 100% is the whole chip. |
| `proc.ratio` | processes → list width | Process pane width in percent, in steps of 5. |
| `keymap` | keys → key profile | `plottypus`, `htop` or `btop`. See [Keys](https://plottypus.com/docs/keys). |

`-i` on the command line accepts anything from 100 ms to 60 s (`250`, `250ms`, `1s`, `1.5s`) for that run. The config file and the settings page stick to the five steps above. Command-line flags (`-i`, `--theme`, `--surface`) apply to that run only; saving other changes does not write them into the file.

## Environment variables

These win over the file.

| Variable | Effect |
| --- | --- |
| `PLOTTYPUS_THEME=<name>` | Use that theme. `auto` reads the terminal. |
| `PLOTTYPUS_ICONS=nerd` | Nerd Font icons in panel titles (`none` for plain ASCII). |
| `PLOTTYPUS_KEYS=htop` | Key profile: `plottypus`, `htop` or `btop`. |
| `PLOTTYPUS_GLASS=on` | Glass: `on`, `off`, `auto`, or an opacity such as `0.8`. |
| `PLOTTYPUS_COLORS=256` | Force colour depth: `truecolor`, `256`, `16` or `none`. |
| `NO_COLOR=1` | Monotreme with attributes only. A `PLOTTYPUS_THEME` name overrides it. |
| `XDG_CONFIG_HOME` | Where `plottypus/config.toml` and `license.toml` live. |

## Old config files

Files from before v1 (flat keys like `show_gpu`, `sort`, `proc_ratio`) still load unchanged. Each old key is moved to its v1 name the first time you change that setting, one key at a time, so nothing is rewritten behind your back.

`plottypus --print-config` prints the effective preferences after flags and exits. In 1.0.0 it prints a short summary using those older flat names (`interval_ms`, `surface`, `theme`, `mouse`, `show_gpu`, `show_net`, `show_disk`, `show_fans`, `show_cores`, `show_threads`, `show_tree`, `sort`, `proc_ratio`), not the full v1 file above. Anything plottypus writes to `config.toml` uses the v1 names.