witr: understand why a process is running

When an unknown process eats CPU, when a port is already taken or when a service keeps coming back, the real question is not what, but why. The classic tools (ps, top, lsof, ss, systemctl, docker ps) show the state, and leave you to correlate by hand. witr (Why Is This Running) answers directly: it traces the ancestry of a process and rebuilds the chain that made it exist (systemd, service, container, shell). This guide shows how to install it and use it to diagnose fast. The outputs shown come from witr 0.3.3, the latest published version, run on Debian 13, Ubuntu 24.04 and AlmaLinux 10.

What you will learn

• Install witr on Linux (binary, package, package manager)
• Trace the origin of a process by name, PID, port, file or container
• Read the ancestry chain (Why It Exists) and the warnings
• Diagnose a busy port or a mysterious process in one command

Why witr rather than ps and lsof

ps and lsof expose the state: a PID, a command, a port. But they do not tell where the process comes from. witr correlates these layers for you and displays the lineage: who started what, through which service or which container, up to systemd.

Question	Classic tool	witr
Which PID, which command?	ps, top	yes
Which process holds this port?	ss -tlnp, lsof -i	witr --port
Why does this process exist?	manual correlation	ancestry chain
Which systemd service manages it?	systemctl status	shown directly

Swipe to see more

Install witr

witr is a static Go binary (Linux, macOS, FreeBSD, Windows). The safest method is to download the binary of the release and check its checksum against the SHA256SUMS file published next to it, rather than running an install script.

Verified binary

VERSION=0.3.3
curl -fsSLO "https://github.com/pranshuparmar/witr/releases/download/v${VERSION}/witr-linux-amd64"
curl -fsSLO "https://github.com/pranshuparmar/witr/releases/download/v${VERSION}/SHA256SUMS"
grep ' witr-linux-amd64$' SHA256SUMS | sha256sum -c -
sudo install -m 755 witr-linux-amd64 /usr/local/bin/witr

The sha256sum -c command must answer witr-linux-amd64: OK before installing (checked on the three distributions). An arm64 binary is published under the same naming scheme.

Debian/RHEL package

# Debian/Ubuntu: download the .deb of the release, then
sudo apt install ./witr-0.3.3-linux-amd64.deb

# RHEL/AlmaLinux/Rocky
sudo dnf install ./witr-0.3.3-linux-amd64.rpm

Ubuntu 26.04 and Debian sid also package witr (sudo apt install witr), but lagging behind: measured on 2026-09-30, sid offers 0.3.1 and Ubuntu 26.04 offers 0.2.4. Debian 13 does not have it.

Package manager

brew install witr        # macOS / Linuxbrew
# also: conda, aur, winget, ports...

Check the installation with the --version flag, which also gives the commit of the build:

witr --version

witr v0.3.3 (commit 86831e80c59c54e19c74cdbd126ed7ff6bcad756, built 2026-06-24T06:47:19Z)

First diagnosis

Query a process by its name. When several match, witr lists the candidates with their PID, here two sleep started from a shell:

witr sleep

Multiple matching processes found:

[1] sleep (pid 3156)
    sleep 601
[2] sleep (pid 3157)
    sleep 602

Re-run with:
  witr --pid <pid>

Then target the PID you want. The output below is that of a sleep 600 started from the shell of a Debian 13 container, copied as is:

witr --pid 3682

Target      : sleep

Process     : sleep (pid 3682)
User        : root
Command     : sleep 600
Started     : just now (Wed 2026-09-30 02:49:38 +00:00)

Why It Exists :
  bash (pid 1) → sleep (pid 3682)

Source      : bash (shell)

Working Dir : /tmp

Warnings    :
  • Process is running as root
  • Process is running from a suspicious working directory: /tmp

The Why It Exists section gives the ancestry chain, and Source says what carries the process: here a shell. On a server, a daemon started by systemd goes back to systemd (pid 1), and witr then adds the service and its unit file (the project README documents the Unit File line for Linux). The Warnings flag points to watch: running as root, unusual working directory.

Target a port, a file or a container

witr is not limited to process names. Its flags cover the most frequent diagnostic questions:

# Which process listens on port 5432?
witr --port 5432

# Which process holds this file open (lock)?
witr --file /var/lib/dpkg/lock

# Where does this container come from?
witr --container redis

# Exact match (no fuzzy search)
witr nginx --exact

# Lineage as a tree, or on a single line for a script
witr --tree --port 8080
witr --short --port 8080

witr --port alone replaces the ss -tlnp | grep reflex followed by a systemctl status, and also traces the lineage of the process found. Measured with an nc -l -p 8080, the output adds a Sockets : 0.0.0.0:8080 (TCP | LISTENING) line, and --short reduces everything to bash (pid 1) → nc (pid 3165). The --file option also finds an inherited descriptor: a file opened by a shell then passed on to the command it started is attributed to that command.

Interactive mode (TUI)

Started without a precise target, witr offers a terminal dashboard (TUI) to browse processes and their lineages interactively. It needs a real terminal: without /dev/tty, it stops on error running tui: could not open a new TTY. The command mode remains better to script or capture an output, with --no-color if it goes to a file.

Use case: a port already taken

The classic scenario: a service refuses to start because its port is busy. Instead of chaining ss, lsof and systemctl, one command is enough:

witr --port 8080

witr identifies the process, and tells whether it comes from a systemd service, a Docker container or a shell, saving you from blindly killing a PID whose origin you do not know.

Key points

• witr answers why a process runs, not only what runs
• It traces the ancestry chain (Why It Exists) up to systemd, and points to the unit file
• Targets: name, --pid, --port, --file, --container
• The Warnings add a security reading (root, suspicious working dir)
• A single Go binary, best installed from the release by checking SHA256SUMS; distribution packages lag one or more versions behind
• Ideal to diagnose fast a busy port or a mysterious process

Knowledge check

Check that the essentials of this guide stuck. The questions cover only what has just been explained here.

Knowledge check

Check what you have learned with this interactive quiz

6 questions

6 min

70% to pass

How it works

• The timer starts when you click Start
• Multiple choice, true/false and short answer questions
• You can move between questions
• Detailed results are shown at the end

Start the quiz

Starts the quiz and the timer

×

See in the glossary →