Stats User Guide

Stats is a free, open-source macOS system monitor that lives in your menu bar. It shows live CPU, GPU, memory, disk, network, battery, sensor, Bluetooth, and clock information as compact widgets, and opens detailed pop-up panels when you click them. Everything runs locally on your Mac, and every monitor is fully configurable.

This guide walks you through installing Stats, turning monitors on, choosing how each one looks in the menu bar, reading the detail pop-ups, and tuning the app to your needs.

Note

Stats is a menu bar utility — there is no main window that stays open. You interact with it almost entirely through the menu bar icons and the Settings window. If you ever lose track of it, open Settings (see Opening Settings) and everything is there.

Table of Contents

1. Quick Start
2. Requirements
3. Installation
4. Core Concepts
5. Turning Monitors On and Off
6. Choosing Menu Bar Widgets
7. The Monitor Modules in Detail
8. Reading the Pop-up Panels
9. The Text Widget and Its Variables
10. Combined (Merged) Modules
11. Application Settings
12. macOS Desktop & Notification-Center Widgets
13. System Stats (Remote Monitoring)
14. Fan Control & Sensors
15. Backing Up & Restoring Your Settings
16. Launch Options
17. Troubleshooting
18. Frequently Asked Questions
19. Reference

1. Quick Start

1. Download Stats.dmg (or run `brew install stats`).
2. Open the DMG and drag Stats into Applications.
3. Launch Stats from Applications.
4. The Settings window opens automatically on first launch.
5. Pick the monitors you want (CPU, RAM, etc.) and choose a widget for each.
6. Watch your stats appear in the menu bar. Click any icon for details.

When you launch Stats for the first time, a short setup screen appears, and then — because no widgets are active yet — the Settings window opens automatically so you can choose what to monitor.

Tip

Start small. Enable CPU and Memory first with the Mini widget, get comfortable clicking the icons to open their pop-ups, then add GPU, Disk, Network, and the rest as you need them. Each active monitor uses a little CPU and energy, so only run what you actually watch.

2. Requirements

Note

If you are on an older macOS release that the current version no longer supports, a legacy build is available at mac-stats.com/downloads.

Some features have additional, automatic requirements that Stats checks for you:

• Battery monitor appears only on Macs that report a power source (i.e. notebooks).
• Fan control requires installing a small privileged helper (see Fan Control & Sensors). It is in legacy maintenance mode.
• macOS desktop widgets require turning on a setting because they are disabled by default (see section 12).

3. Installation

Stats can be installed manually from a disk image or through Homebrew. Both deliver the same app.

Manual (DMG)

1. Download the latest release: Stats.dmg.
2. Open the downloaded Stats.dmg.
3. Drag the Stats app into your Applications folder.
4. Eject the disk image and launch Stats from Applications.

Homebrew

Open the Terminal app and run:

brew install stats

Expected result:

==> Installing Cask stats
🍺  stats was successfully installed!

Launch Stats from Applications (or with open -a Stats).

Important

Stats updates itself. When a new version is available it can download and install the update for you (controlled by the Check for updates setting). If you installed through Homebrew you can also update with brew upgrade stats, but the built-in updater works regardless of how you installed.

First launch

On the very first launch you may see a brief setup window. After it finishes, Stats opens Settings automatically because nothing is being monitored yet. Choose your monitors there (next sections).

Note

macOS may warn that Stats was downloaded from the internet. This is normal for any app distributed outside the App Store — open it once via the Applications folder to confirm.

4. Core Concepts

Stats is built around a few simple ideas. Understanding them makes everything else obvious.

Module : A single monitor — CPU, GPU, RAM (memory), Disk, Sensors, Network, Battery, Bluetooth, Clock, or Remote. Each module can be turned on or off independently.

Widget : The compact visual that a module draws in the menu bar — for example a percentage number, a line chart, or a battery icon. A module can offer several widget styles, and you choose which ones to show.

Pop-up : The detailed panel that appears when you click a module's menu bar widget. It shows the full breakdown (per-core load, top processes, network addresses, battery health, and so on).

Settings : Per-module options (colors, update frequency, which disk or GPU to track, etc.) plus global application settings. Reached from the Settings window or the gear icon inside any pop-up.

The relationship is: a module reads data → draws one or more widgets in the menu bar → opens a pop-up with details when clicked.

Tip

A module only appears in the menu bar if it is enabled and has at least one active widget. If you enable a module but see nothing, you probably haven't picked a widget for it yet.

5. Turning Monitors On and Off

Opening Settings

There are several ways to open the Settings window:

• Click any Stats menu bar icon to open its pop-up, then click the ⌘ (command) button in the pop-up header.
• If Stats is paused or showing its app icon, click the icon.
• Re-open the app from Applications (Stats brings Settings to the front).

The Settings window has a sidebar listing the Dashboard plus every available module, and a main area showing the selected item's options.

Enabling a module

1. Open Settings.
2. Select a module in the sidebar (e.g. CPU).
3. Use the toggle in the window toolbar to switch the module on or off.

When you enable a module, Stats immediately starts reading its data and shows its widget(s) in the menu bar. When you disable it, its menu bar items disappear and it stops reading data (saving energy).

Note

Stats remembers each module's on/off state across restarts. Modules that aren't supported on your Mac (for example Battery on a desktop, or Fan readings without the helper) are hidden or stay off automatically.

The Dashboard

The Dashboard entry at the top of the sidebar is read-only system information about your Mac:

6. Choosing Menu Bar Widgets

Each module's settings page lets you pick which widget(s) appear in the menu bar. You can enable more than one widget per module (for example a number and a line chart).

Stats offers the following widget styles (each module supports the subset that makes sense for its data — see section 7):

Tip

To reorder the icons of different apps in the menu bar (including Stats' own icons), hold ⌘ (command), drag the icon to where you want it, and release ⌘. macOS — not Stats — controls this ordering, so it may shuffle once after the first reboot following installation.

Most widgets expose their own small settings (colors, value to display, whether to show a frame, etc.) directly under the widget picker on the module's settings page.

7. The Monitor Modules in Detail

This section covers each module, the data it shows, the widgets it supports, and its notable options. All values, colors, and behaviors here come directly from how the module is built.

7.1 CPU

Monitors processor load.

Widgets: Mini, Line chart, Bar chart, Pie chart, Tachometer.

Key options:

• Show usage per core — the bar chart draws one bar per logical core instead of a single total bar.
• Split the value (system / user) — splits load into system and user portions, each with its own color (defaults: system = red, user = blue).
• Group by clusters — on Apple Silicon, groups load into efficiency, performance, and super core clusters, each with its own color (defaults: e‑cores = teal, p‑cores = indigo, s‑cores = orange).
• Colors — system, user, efficiency, performance, and super core colors are all customizable (including a custom color picker).

Pop-up shows: total usage, per-core breakdown, system/user/idle split, average load (1/5/15 min), temperature, frequency (Apple Silicon) or scheduler limits (Intel), and the top processes by CPU.

Note

CPU temperature sensors are thermal zones, not per-core readings. A label like "CPU Efficiency Core 1" is one temperature sensor inside the efficiency cluster, not the temperature of a single core.

7.2 GPU

Monitors graphics processor utilization.

Widgets: Mini, Line chart, Bar chart, Tachometer.

Key options:

• Show GPU type — prefixes the Mini widget value with the GPU type (iGPU integrated, eGPU external, dGPU discrete).
• GPU selection — if your Mac has more than one GPU, choose which one the widget tracks.
• Update interval — how often utilization is read.

Pop-up shows: utilization, render/tiler/ANE utilization where available, temperature, core/memory clock, fan speed, and FPS where the hardware exposes it.

7.3 RAM (Memory)

Monitors memory usage and pressure.

Widgets: Mini, Line chart, Bar chart, Pie chart, Memory, Tachometer, State (dot), Text.

Key options:

• Split the value — bar/pie/tachometer/memory widgets split memory into app, wired, and compressed segments (default colors: app = blue, wired = orange, compressed = pink).
• Memory pressure — Mini, Line chart, Bar chart, and Memory widgets reflect macOS memory pressure; the State dot is colored by pressure level.
• Text widget value — a custom template (default $mem.used/$mem.total ($pressure.value)); see section 9.

Pop-up shows: total/used/free, app/wired/compressed, cached, swap (used/total/free), swap‑ins/outs, memory pressure, and the top processes by memory.

7.4 Disk

Monitors drive capacity and read/write activity.

Widgets: Mini, Bar chart, Memory, Pie chart, Speed, Network chart, Text.

Key options:

• Disk selection — choose which drive the widget tracks (defaults to the root/boot volume).
• Main color — color used by the pie chart (default blue).
• Text widget value — default $capacity.free/$capacity.total; see section 9.

Pop-up shows: each drive's capacity (total/used/free), read/write activity, file system and connection type, and SMART data (drive health %, temperature, total read/written, power cycles, power-on hours) where available.

Note

When you use the Speed or Network chart widget to show disk I/O, Stats automatically reads activity once per second so the chart stays smooth.

7.5 Network

Monitors upload/download bandwidth and connection details.

Widgets: Speed, Network chart, Text, State (dot for connectivity).

Key options:

• Public IP refresh interval — how often the public IP address is refreshed: never (default), hourly, every 12 hours, or every 24 hours.
• Reset total usage — optionally reset the cumulative upload/download totals at app start.
• Widget activation threshold — only "light up" the widget when transfer exceeds a threshold you set (with a size unit such as KB/MB/GB), keeping the menu bar quiet during idle periods.
• Connectivity (ICMP) host — Stats can ping a host to report up/down status and latency; you can change or disable the host.
• Text widget value — default $addr.public - $status; rich set of variables in section 9.

Pop-up shows: local and public IPv4/IPv6 addresses, DNS servers, interface name and type (Wi‑Fi/Ethernet/Bluetooth/other), Wi‑Fi details (SSID, BSSID, RSSI, noise, standard, channel, security), current and total bandwidth, and the top processes by network use.

Note

To show your public IP, Stats asks api.mac-stats.com for it. See External services for details and how to disable this.

7.6 Battery

Monitors battery level, charging, and health. Available only on Macs with a battery.

Widgets: Mini, Bar chart, Battery, Battery details.

Pop-up shows: charge level, charging/AC status, optimized-charging status, time to full/empty, cycle count, health (%), capacities (design/max/current), amperage, voltage, temperature, and adapter details (power, voltage, charging current/voltage).

Tip

You can set low/high battery notifications in the Battery module's settings so Stats alerts you when the level crosses a threshold.

7.7 Sensors

Monitors temperature, voltage, power, and fan sensors via the SMC.

Widgets: Mini (single selected sensor), Stack (multiple sensors), Bar chart (fans).

Key options:

• Sensor selection — choose which sensors are shown and, for the Mini widget, which single sensor is displayed (default Average System Total).
• Fan value — show fan speed as a percentage (default) or as RPM.
• Show unknown / HID sensors — reveal additional discovered sensors.

Caution

The Sensors and Bluetooth modules are the most resource-intensive. If you want to reduce Stats' energy/CPU footprint, disabling these two can cut its usage by up to ~50% in some cases.

7.8 Bluetooth

Shows battery levels of paired/connected Bluetooth devices (AirPods, mice, keyboards, controllers, etc.).

Widgets: Stack (one row per device/battery reading).

Key options: per-device visibility and optional low-battery notification thresholds.

7.9 Clock

Shows one or more clocks, including multiple time zones and calendars.

Widgets: Stack.

Key options:

• Add multiple clocks, each with its own name, time-zone, calendar, and date format string (e.g. yyyy-MM-dd HH:mm:ss).
• Time zones include Local plus fixed UTC offsets (UTC‑12:00 through UTC+14:00, including half/quarter-hour offsets) and all named IANA zones.
• Calendars include Gregorian (default), Buddhist, Chinese, Coptic, Ethiopic, Hebrew, ISO‑8601, Indian, Islamic (and variants), Japanese, Persian, and ROC; macOS 26 adds several more (Bangla, Tamil, Vietnamese, and others).

Tip

The Clock pop-up header has a calendar button that opens the macOS Calendar app.

7.10 Remote

Connects Stats to System Stats, an online dashboard that aggregates monitoring from multiple machines and external hosts. See section 13.

Widgets: State (a single dot summarizing whether your remote machines/hosts are all up, all down, or mixed).

Pop-up shows: your remote machines and monitored hosts with online/up/down status, grouped as configured in your System Stats account.

8. Reading the Pop-up Panels

Click any module's menu bar widget to open its pop-up. The pop-up has a header with three controls:

Pop-ups resize to fit their content and scroll if they're taller than your screen. Click elsewhere (or press the close button that appears when you drag the pop-up) to dismiss it.

Tip

You can assign a keyboard shortcut to open a module's pop-up. Set it in the module's pop-up settings; pressing the shortcut anywhere toggles that pop-up open/closed.

9. The Text Widget and Its Variables

The Text widget (available for RAM, Disk, and Network) renders a string you define, substituting live values for $variables. Variables use the form $group.field (or just $group for single-value ones).

Memory (RAM) variables

Default: $mem.used/$mem.total ($pressure.value)

Disk variables

Default: $capacity.free/$capacity.total

Network variables

Default: $addr.public - $status

Example (Network):

$wifi.ssid · $download/$upload · $status

renders as something like:

HomeWiFi · 1.2 MB/s/240 KB/s · UP

10. Combined (Merged) Modules

By default each module occupies its own menu bar slot. Combined modules merges all enabled modules into a single menu bar item, which saves space.

Enable it in Settings → application settings → Combined modules:

Note

Reordering modules here also sets the order they appear in the combined item and in the combined pop-up.

11. Application Settings

Open Settings and select the application-settings area (the gear/options section, reachable from the Dashboard area). These options apply to Stats as a whole.

There is also a Stress tests section (run an Efficiency cores, Performance cores, or GPU load test) that's useful for verifying temperature/fan behavior under load.

Important

Turning on Show icon in dock also makes Stats behave like a regular app (it appears in the Dock and ⌘-Tab switcher). Turn it off to return to a pure menu bar utility.

12. macOS Desktop & Notification-Center Widgets

Stats can publish data to native macOS widgets (the ones you add to your desktop or Notification Center). These are off by default.

To enable them:

1. Open Settings.
2. Turn on macOS widgets.
3. Add a Stats widget the normal macOS way (right-click the desktop → Edit Widgets, or open Notification Center → Edit Widgets, and find Stats).

Warning

macOS widgets are disabled by default on purpose. The system process that feeds widgets (chronod) can generate heavy load, so Stats only sends data once you opt in with the macOS widgets switch. If your desktop widget shows no data, this setting is almost always the reason.

13. System Stats (Remote Monitoring)

System Stats is an optional online service (app.system-stats.com) that collects monitoring from one or more Macs and external hosts into a single dashboard. The Remote module and the System Stats settings section connect Stats to it.

Configure it in Settings → System Stats:

Caution

Enabling Control lets the remote service perform control actions on this machine. Stats shows a warning before enabling it — leave it off unless you specifically need remote control and understand the implications.

Note

System Stats is a separate, optional cloud service. You can use every local monitor in Stats without ever logging in.

14. Fan Control & Sensors

Stats can read fan speeds (in the Sensors module) and, on supported Macs, control them. Fan control requires a small privileged helper to be installed, which macOS will prompt you to authorize with your administrator password.

Warning

Fan control is in legacy maintenance mode. It does not receive new features or fixes and is kept only because it still works acceptably on older Macs. Treat it as a best-effort feature.

To uninstall the fan helper later, open Settings and use Uninstall fan helper (this option only appears when the helper is installed).

Caution

Sensor labels such as "CPU Efficiency Core 1" identify a thermal sensor in a cluster, not an individual core's temperature. Apple changes sensor keys with each new chip, so some sensors on the newest hardware may be unlabeled or missing until support is added.

15. Backing Up & Restoring Your Settings

All of Stats' preferences can be exported to a file and restored later — handy when setting up a new Mac.

Tip

Export your Stats.plist after you've tuned everything the way you like. Importing it on another Mac reproduces your exact layout, colors, and module choices.

16. Launch Options

Stats accepts a few command-line arguments, useful for scripting or troubleshooting. Launch it from Terminal like this:

/Applications/Stats.app/Contents/MacOS/Stats --reset

Note

--mount-path and --dmg-path are used by the auto-updater to clean up after installing a new version; you normally never pass them yourself.

17. Troubleshooting

Each entry uses the format Symptom → Cause → Solution.

Stats icons do not appear in the menu bar

Cause: macOS 26 introduced a privacy control that requires apps to be explicitly allowed to show menu bar items, even when Stats is running with active widgets.

Solution: Open System Settings → Menu Bar and toggle Stats ON.

Prevention: After any major macOS upgrade, re-check this setting.

Desktop / Notification-Center widget shows no data

Cause: Communication with macOS widgets is disabled by default (to avoid heavy chronod load).

Solution: Open Settings and turn macOS widgets ON, then re-add the widget.

A module is enabled but nothing shows in the menu bar

Cause: The module has no active widget, or Combined modules is hiding it.

Solution: Open the module's settings and enable at least one widget. If using Combined modules, confirm the module is enabled and present in the module strip.

Network shows "DOWN" even though the internet works

Cause: Intermittent interface status detection; reported in community issues (e.g. #2545, #3293).

Solution: Quitting and re-launching Stats reliably clears the false "DOWN" state. Make sure you're on the latest version, where detection has been improved.

Public IP is blank in the Network pop-up

Cause: The public-IP lookup uses api.mac-stats.com; if you block it with a network filter (e.g. Little Snitch), the public IP can't be retrieved.

Solution: Allow api.mac-stats.com, or accept that the public IP and update checks won't work while it's blocked.

"Install Fan Helper does not work" / fan helper won't install

Cause: The privileged helper installation can fail in some environments (reported in #3330, #3331, #3332).

Solution: Approve the administrator-password prompt when it appears. If a previous helper is in a bad state, use Settings → Uninstall fan helper, then try installing again. Remember fan control is legacy and unsupported.

High CPU usage from Stats

Cause: Reading some metrics is inherently expensive; Sensors and Bluetooth are the heaviest. On some chips a specific module can spike a core (e.g. #3294).

Solution: Disable Sensors and/or Bluetooth, or increase the update interval for heavy modules. Make sure you're on the latest version.

After an update, Stats won't open / fails Gatekeeper

Cause: In rare cases an update could corrupt framework symlinks (#3218).

Solution: Delete Stats from Applications and reinstall the latest Stats.dmg.

The app crashed

Cause: Various.

Solution: First confirm you're on the latest version — a fix may already be released. If still crashing, search existing issues before opening a new one.

18. Frequently Asked Questions

Q: Is Stats free? Yes. Stats is completely free and open source under the MIT license.

Q: How do I change the order of the menu bar icons? Hold ⌘ (command), drag the icon to the position you want, and release ⌘. macOS controls icon order, so it may change once after the first reboot following installation.

Q: How do I reduce Stats' energy impact or CPU usage? Disable modules you don't need — especially Sensors and Bluetooth, the two most expensive. You can also lengthen each module's update interval.

Q: Why does the Sensors module show the "wrong" number of CPU/GPU cores? Those are thermal sensors (thermal zones), not cores. Each cluster contains several sensors that don't map one-to-one to cores.

Q: What external servers does Stats contact, and can I block them? api.mac-stats.com (update checks + public IP), api.github.com (fallback update check), and — only if you use Remote — app.system-stats.com. You can block the first two with a network filter; you'll just lose update checks and public-IP display.

Q: Does Stats support Windows or Linux? No. Stats is a macOS application.

Q: How do I monitor a specific disk or GPU instead of the default? In the Disk or GPU module settings, choose the drive/GPU you want from the selector.

Q: Can I get a notification when my battery is low or memory pressure is high? Yes — several modules (Battery, RAM, CPU, GPU, Disk, Sensors, Network, Bluetooth) support notifications you can configure in their settings.

Q: How do I show multiple time zones? In the Clock module, add a clock for each zone, each with its own name, time zone, calendar, and format.

Q: My menu bar is crowded. Can Stats use just one icon? Yes — turn on Combined modules to merge everything into a single menu bar item.

Q: Can I move my Stats setup to a new Mac? Yes — Export settings to a Stats.plist on the old Mac and Import settings on the new one.

Q: Why was my GitHub issue closed without a response? Most likely it duplicates an existing issue that already has an answer. Search closed issues for your topic.

Q: How can I contribute or request a feature? Open an issue first to discuss it. Pull requests are expected to map to a discussed issue (language/translation changes are an exception).

Q: What languages does Stats support? Many — including English, German, French, Spanish, Italian, Portuguese, Russian, Ukrainian, Polish, Czech, Dutch, Turkish, Korean, Japanese, Simplified and Traditional Chinese, and more than two dozen others contributed by the community.

19. Reference

Modules at a glance

Default values

External services

Useful links

• Releases & downloads: https://github.com/exelban/stats/releases
• Legacy builds: https://mac-stats.com/downloads
• Issue tracker: https://github.com/exelban/stats/issues
• License (MIT): https://github.com/exelban/stats/blob/master/LICENSE