Skip to main content

LinuxPilot

LinuxPilot is a simple command-line tool that checks the health of a Linux machine. It works on servers, desktops and Raspberry Pi.

Run one command and it tells you what is fine, what needs attention, why it matters, and what to check next.

  • Read-only. It never changes your system.
  • No background service. It runs, prints the result, and exits. Live views run only while you keep them open and stop when you quit.
  • No dependencies. Only Python 3.9 or newer is needed.
  • No root needed for normal use.
  • Sends no data anywhere.

Example

$ linuxpilot
LinuxPilot 0.1.0 | web-01 | Ubuntu 24.04 LTS | up 41 days, 3h   checked in 0.6s

  [WARN] 1 warning needs attention

  [ OK ] System                       Ubuntu 24.04 LTS, kernel 6.8.0, x86_64, up 41 days
  [ OK ] CPU load                     0.40 / 0.52 / 0.61 (1/5/15 min) on 4 cores
  [ OK ] CPU usage        #.........  7% busy over 0.5s
  [ OK ] CPU temperature              52°C (coretemp)
  [ OK ] Memory           ###.......  2.1 GB / 7.8 GB used (27%)
  [WARN] Disk /           #########.  91% used (45.6 GB / 50.0 GB, 4.4 GB free)
  [ OK ] Internet                     reachable (1.1.1.1 in 9 ms)

Needs attention
  1. [WARNING] Disk /: 91% used (45.6 GB / 50.0 GB, 4.4 GB free)
     Why:  / is 91% full. When a filesystem fills up, databases, logs and package
           updates start failing.
     Next: Find what is using space: `sudo du -xh --max-depth=2 / | sort -h | tail -20`

Overall: WARNING  |  0 critical, 1 warning, 6 ok

The values above are only an example. In a normal terminal the output is in color, with symbols and solid usage bars, and a short animation runs while it checks. When the output goes to a file or another program, it stays plain.

Install

You can install LinuxPilot with pip, pipx or uv. Pick the one you already use. If you are not sure, use pipx.

Method Best for
pip Virtual environments, or systems that allow pip installs
pipx Most users, especially on Debian, Ubuntu and Raspberry Pi OS
uv People who already use uv

Option 1: pip

pip install linuxpilot

On newer Debian, Ubuntu and Raspberry Pi OS this may fail with an externally-managed-environment error. This is normal: these systems block pip from installing into the system Python to protect system packages. Either use pipx or uv instead, or install inside a virtual environment:

python3 -m venv ~/.venvs/linuxpilot
~/.venvs/linuxpilot/bin/pip install linuxpilot
~/.venvs/linuxpilot/bin/linuxpilot

Option 2: pipx

pipx installs command-line tools in their own isolated environment and makes the command available everywhere.

Install pipx first.

Debian, Ubuntu, Raspberry Pi OS:

sudo apt update
sudo apt install pipx
pipx ensurepath

Fedora:

sudo dnf install pipx
pipx ensurepath

Close and reopen your terminal, then install LinuxPilot:

pipx install linuxpilot

Option 3: uv

If you do not have uv yet, see the uv installation guide. Then run:

uv tool install linuxpilot

Run it

linuxpilot

That is all you need for everyday use.

Common commands

Command What it does
linuxpilot Run all checks and show a summary
linuxpilot -v Show more details for every check
linuxpilot --only disk,memory Run only some checks
linuxpilot --skip network Run everything except some checks
linuxpilot --no-network Do not contact the internet
linuxpilot --quick Skip the short CPU measurement
linuxpilot --json Print the result as JSON
linuxpilot --ascii Use plain text markers like [ OK ], as in the example above
linuxpilot watch Live, interactive view in the terminal, press q to quit
linuxpilot serve Live dashboard in your browser, press Ctrl+C to stop
linuxpilot list-checks List all available checks
linuxpilot --help Show help

Live view

Use a live view when you want to keep an eye on a machine for a while, for example during a backup, an update or a heavy job. Nothing runs in the background. The live view lasts only while the command is open, and stops completely when you quit.

In the terminal

linuxpilot watch

This opens an interactive view that refreshes every 5 seconds. It works over a plain SSH connection, needs nothing extra installed, and opens on the most serious problem with its explanation already shown.

At the top you see the overall result and small live graphs of CPU, memory, load and temperature. Below that is the list of checks, with usage bars for disk, memory and CPU.

Keys:

Key What it does
Up / Down (or j / k) Move between checks
Enter or Space Open or close the details of a check
e Open or close all checks
f or Tab Show all checks, only problems, or only OK
/ Search by name (Enter keeps it, Esc clears it)
r Check again now
p Pause or resume
+ / - Refresh less often or more often
c Copy the suggested command
v Show checks that do not apply to this machine
? Show all keys
q or Esc Quit

Ctrl+C also quits, and Ctrl+Z pauses it in the background like any other program (fg brings it back). Your terminal is always restored when you leave.

The copy key uses a standard terminal feature that most modern terminals support, including over SSH. If your terminal does not support it, select the command with the mouse.

Useful options:

linuxpilot watch --interval 10        # refresh every 10 seconds (minimum 2)
linuxpilot watch --only cpu,memory    # watch only some checks
linuxpilot watch --plain              # simple refreshing report without keys
linuxpilot watch --json >> log.jsonl  # write one JSON line per refresh to a file

In the browser

linuxpilot serve

Then open http://127.0.0.1:8765 in your browser. The page updates on its own and shows what needs attention at the top. Press Ctrl+C in the terminal to stop. After that the page shows that it is disconnected.

What you can do on the page:

  • Click any check to see its measured values, where the data came from, and any notes.
  • Show only problems or only OK checks, or type in the box to find a check by name.
  • Watch small graphs of CPU, memory, load and temperature since you opened the page.
  • Choose how often it refreshes, press Refresh now, or Pause it.
  • Press Copy next to a suggested command to copy it.

The page remembers your filter and refresh rate in that browser. The graphs are kept only in the open tab and are gone when you close it.

Options:

linuxpilot serve --open            # also open the page in your browser
linuxpilot serve --port 9000       # use another port
linuxpilot serve --interval 10     # refresh every 10 seconds

The page works offline and loads nothing from the internet. It only shows information and cannot change anything on the machine.

Viewing a server or Raspberry Pi from your laptop

By default only the machine itself can open the dashboard. The safe way to see it from your laptop is an SSH tunnel, which needs no open ports and no extra setup:

  1. On your laptop, connect with a tunnel:
    ssh -L 8765:127.0.0.1:8765 user@your-server
    
  2. In that SSH session, start the dashboard:
    linuxpilot serve
    
  3. On your laptop, open http://127.0.0.1:8765

When you close the SSH session or press Ctrl+C, the dashboard stops.

If you really want other computers on your network to open it directly, use:

linuxpilot serve --host 0.0.0.0 --allow-remote

LinuxPilot then prints a link with a random access token. Only people with the full link can see the data. The connection is not encrypted, so only do this on a network you trust, or use a VPN such as Tailscale or WireGuard instead.

What it checks

Area Checks
System OS, kernel, uptime, reboot required after updates
CPU Load, usage, I/O wait, temperature
Memory Memory and swap use, memory pressure, processes killed for lack of memory
Disk Free space, inodes, disks that became read-only unexpectedly
Services Failed systemd services and why they failed
Network Default route, network interfaces, DNS, internet access
Raspberry Pi Low voltage and CPU throttling

Some checks only run where they make sense. For example, temperature is usually not available on cloud servers and virtual machines, and the Raspberry Pi check only runs on a Pi. These are shown as "not applicable" instead of as errors.

Why I built this

Checking on my servers and Raspberry Pi meant running a dozen commands and working out what the output meant. I wanted one small tool that tells me plainly what is wrong, why it matters, and what to check next, and that runs only when I ask it to.

It is still early. Feedback is very welcome, especially from people running it on a Raspberry Pi or a distribution other than Ubuntu.

Understanding the results

Each check gets one of these results:

Result Meaning
ok Healthy
warning Needs attention soon
critical Needs attention now
unknown LinuxPilot could not read this, for example because of permissions
unsupported Does not apply to this machine
skipped You chose not to run it

Using it in scripts

LinuxPilot returns an exit code you can use in scripts or cron jobs:

Exit code Meaning
0 Everything is OK
1 At least one warning
2 At least one critical problem
64 Wrong command or option
70 Could not start, for example because the dashboard port is already in use

The live views (watch and serve) exit with 0 when you quit them with q or Ctrl+C.

Example:

linuxpilot --quick > /dev/null || echo "Something needs attention"

Show only the problems as JSON (requires jq):

linuxpilot --json | jq '.findings[] | select(.status != "ok")'

Default limits

Check Warning Critical
Disk space used 85% 95%
Memory available below 10% below 5%
CPU load per core (5 min) 1.5 3.0
CPU temperature 80°C 90°C

Raspberry Pi note

If the Pi check shows a permission message, add your user to the video group, then log out and log back in:

sudo usermod -aG video $USER

Privacy

LinuxPilot does not collect or upload anything. The only network checks are one DNS lookup of example.com and one connection to 1.1.1.1. Use --no-network to turn them off.

The browser dashboard only listens on 127.0.0.1 (this machine) unless you choose otherwise with --allow-remote.

Update and uninstall

Use the same tool you installed with:

Method Update Remove
pip pip install --upgrade linuxpilot pip uninstall linuxpilot
pipx pipx upgrade linuxpilot pipx uninstall linuxpilot
uv uv tool upgrade linuxpilot uv tool uninstall linuxpilot

If you installed into a virtual environment, use that environment's pip, or just delete the environment folder to remove it.

Run from source

If you want to try it without installing from PyPI:

git clone https://github.com/nideshpandey/linuxpilot.git
cd linuxpilot
python3 -m venv .venv
. .venv/bin/activate
pip install -e ".[dev]"
linuxpilot

Run the tests with pytest.

Contributing

Bug reports and pull requests are welcome. See CONTRIBUTING.md for the project principles and how checks are built and tested.

If you run LinuxPilot on a Raspberry Pi or a distribution other than Ubuntu, sharing the output of linuxpilot -v in an issue helps a lot.

License

MIT

Metadata

Release files for linuxpilot 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for linuxpilot 0.1.0
File Size Uploaded Provenance Actions
linuxpilot-0.1.0.tar.gz 72.7 kB Without provenance Details for linuxpilot-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for linuxpilot 0.1.0
File Interpreter ABI Platform Actions
linuxpilot-0.1.0-py3-none-any.whl Python 3 none any Details for linuxpilot-0.1.0-py3-none-any.whl

Total release size: 137.6 kB

Release files / linuxpilot-0.1.0.tar.gz

Download URL linuxpilot-0.1.0.tar.gz
Size 72.7 kB
Tags Source
SHA-256 checksum
How to use checksums
b98ca31ea8a7eab8bca7bf85cd4b9e4a9c60477235cc8e6f18e0718f90d1366e
BLAKE2b-256 checksum
How to use checksums
c2ae13ef872f63d4feca77d28a2d5e2cdcf7a4502077e5c20c2331b0bc3f8149
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.11.14 {"installer":{"name":"uv","version":"0.11.14","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Release files / linuxpilot-0.1.0-py3-none-any.whl

Download URL linuxpilot-0.1.0-py3-none-any.whl
Size 64.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
f848dc2ca9308d74eb241a875c009a41577abf100d4928daa8df8e4eaa7b68c9
BLAKE2b-256 checksum
How to use checksums
43ff14762bda5b5793851eba51c159f8a6c7895885f22248ee91384cf2fb3eb0
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.11.14 {"installer":{"name":"uv","version":"0.11.14","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Security for linuxpilot 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page