Linux command: watch

1. The Basics

watch runs a command over and over and shows you the output on a cleared screen. That is all it does. Everything interesting comes from the details of how it runs the command, and from the fact that it is not the tool most people assume it is.

1.1 The Simplest Possible Use

Put watch in front of any command:

$ watch date

The screen clears and fills with two things, a header and the output:

Every 2.0s: date                              xps: Sun Aug 23 21:13:02 2026

Sun Aug 23 09:13:02 PM CEST 2026

Every two seconds the command runs again and the screen is redrawn. Ctrl-C stops it. There is no other way out, which surprises people who expect q to work: watch is not a pager.

1.2 Reading the Header

The header is four pieces of information and it is worth knowing them, because two of them answer the questions you are most likely to ask while staring at the screen.

That last point is the one to remember. A frozen clock in the header means your command has not returned, not that watch has died.

1.3 The Interval Is a Gap, Not a Schedule

Almost everyone reads -n 5 as "run this every five seconds". It does not mean that. It means "wait five seconds after the command finishes, then run it again". If the command is slow, the cycle is slower than you asked for.

Here is a command that takes two seconds, with the interval set to half a second, logging the moment each run starts:

$ watch -n 0.5 'date +%s.%N >> t.log; sleep 2'

# gaps between runs, in seconds:
2.5   2.5   2.5

Not 0.5. Not 2.0. The interval plus the runtime, every time. This is why a watch on something slow, a database query, a du over a large tree, a command that does a DNS lookup, drifts steadily away from the rhythm you thought you set. Section 6.3 shows the option that fixes it, and section 7.1 shows the case where even that cannot help.

The right mental model: watch is a loop that sleeps between runs, not a scheduler that fires at intervals. Every quirk in this article follows from that sentence and from the shell in section 5.1.

3. A Short History

watch is older than most of the tools people compare it to, and it has been rewritten more than once. The copyright file on any Debian or Ubuntu machine still carries the original name:

$ grep -A3 "Tony Rems" /usr/share/doc/procps/copyright
Copyright: 1998-2004 Albert Cahalan
           1991 Tony Rems <This email address is being protected from spambots. You need JavaScript enabled to view it.>
           1993 Larry Greenfield
           1996 Charles Blake

Two things follow from that timeline and both matter in practice.

First, watch is not in POSIX and never has been. It is a Linux convenience from the procps family, so it is not guaranteed on a BSD, on macOS (where you install it from Homebrew), or inside a minimal container image. A script that depends on it is a script that will fail somewhere, and section 6.4 covers what to write instead.

Second, the options are not uniform across machines. The newest ones (-q, -r, -w) are absent on older servers, so check before you rely on them:

$ watch --version
watch from procps-ng 4.0.4

5. Moderate Use Cases

5.1 The Quoting Rule, Which Is the Whole Game

More watch confusion comes from this than from everything else combined. Your shell processes the command line before watch ever sees it. Then watch hands what is left to sh -c, a second shell, for every single refresh.

Two shells, and the difference is visible. Here is the same command written three ways, with the outer shell's own PID being 468449:

$ echo $$
468449

$ watch -t echo $$
468449                             # frozen: YOUR shell expanded it, once

$ watch -t echo '$$'
468474                             # a new number every refresh: watch's sh did it
468476
468478
468480

$ watch -t -x echo '$$'
$$                                 # no shell at all, so nothing expanded it

Read those three results until they make sense, because they are the whole model. Unquoted, your shell substitutes the value once and watch repeats a fixed string forever. Quoted, the substitution happens inside watch, fresh each cycle. With -x, there is no shell to substitute anything.

The practical rule is short: if the command contains anything the shell cares about, quote the whole thing. That means $, |, >, &&, *, backticks and semicolons.

5.2 Pipes Belong Inside the Quotes

This is the same rule, but it deserves its own demonstration because the failure is silent rather than noisy:

$ watch ls /etc | head -3
# the whole of /etc fills the screen.
# the pipe applied to WATCH's output, not to ls.

$ watch 'ls /etc | head -3'
adduser.conf
alsa
alternatives                       # correct

Nothing errors in the first case. Your shell built a pipeline out of watch itself, watch took over the screen anyway, and head sat there with nothing useful to do. You get a plausible-looking screen that is not what you asked for, which is the worst kind of wrong.

The same trap applies to redirection and to chaining:

$ watch 'systemctl is-active nginx && curl -s -o /dev/null -w "%{http_code}" localhost'
$ watch 'tail -5 /var/log/syslog 2>&1'

5.3 When to Use -x

-x (short for exec) skips the sh -c entirely and runs your command directly. Use it when the extra shell is causing you grief rather than helping:

$ watch -x kubectl get pods -o wide
$ watch -x php artisan queue:monitor default

The trade is that you lose every shell feature. Pipes, redirects, variables and globs stop being special and become ordinary arguments:

$ watch -x ls /etc '|' head
ls: cannot access '|': No such file or directory
ls: cannot access 'head': No such file or directory

If you need both a pipeline and -x, you have to supply the shell yourself, at which point you may as well not use -x:

$ watch -x sh -c 'echo ok | tr a-z A-Z'
OK

In practice -x earns its place with commands carrying awkward arguments, JSON, braces, quotes inside quotes, where getting the nesting right for sh -c is more trouble than the shell is worth.

5.4 You Only Get the First Screenful

watch shows what fits and discards the rest. It does not scroll, it does not page, and there is no key to see more. A hundred-line file in a ten-row terminal shows eight lines:

$ seq 1 100 > hundred.txt
$ watch cat hundred.txt            # in a 10-row terminal

Every 2.0s: cat hundred.txt                   xps: Sun Aug 23 21:17:11 2026

1
2
3
4
5
6
7
8                                  # lines 9 to 100 are simply gone

This is not a bug to work around, it is a constraint to design for. Make the command produce a summary rather than a dump:

$ watch 'tail -20 /var/log/nginx/error.log'
$ watch 'ls -1 /var/spool/queue | wc -l'
$ watch 'df -h | grep -E "^/dev|Filesystem"'
$ watch 'ps aux --sort=-%mem | head -12'

The last one is the pattern worth internalising: sort by what you care about, then take the top few. A screen that always fits is a screen you can read at a glance, which is the entire point of the tool.

5.5 Long Lines

By default a line longer than the terminal wraps onto the next row, which eats your limited vertical space and makes a table unreadable. -w truncates instead:

$ watch -w 'ps aux --sort=-%cpu | head -15'

For anything with columns, truncating is almost always the better choice: a cut-off table still lines up, a wrapped one does not.

5.6 Watching the Kernel's Own Files

watch and the /proc filesystem were made for each other, and the reason is a detail most people never notice. The files in /proc are not files. They have no contents until you read them, and the kernel generates the answer at that moment:

$ ls -l /proc/meminfo /proc/loadavg
0 /proc/loadavg
0 /proc/meminfo                    # zero bytes, both of them

$ cat /proc/uptime
215685.54 3283350.21
$ cat /proc/uptime
215686.54 3283365.06               # a second later, a fresh answer

Every refresh is therefore a genuinely new reading of live kernel state, taken with nothing more exotic than cat. That makes a large amount of what the kernel knows available to a one-line command:

$ watch -d 'cat /proc/loadavg'
$ watch -d 'cat /proc/meminfo'
$ watch -d 'grep -E "^(procs_running|procs_blocked)" /proc/stat'
$ watch -n 2 'cat /proc/mdstat'              # a RAID rebuild, the classic use
$ watch -d 'cat /proc/net/dev'

/sys works the same way for hardware and driver state, usually one value per file:

$ watch -n 5 'cat /sys/class/thermal/thermal_zone0/temp'
20000                              # millidegrees, so 20 C

$ watch -n 1 'cat /sys/class/net/eth0/statistics/rx_bytes'

That last one comes with the single most important limitation in this whole article, and it catches people who are otherwise using watch well. rx_bytes is a total, not a rate. It only ever climbs, and watching it climb tells you nothing about how fast traffic is flowing.

To get a rate you need two readings and the time between them, and watch keeps no memory of the previous refresh. It cannot subtract. Anything of the form "per second" is therefore outside what it can do, no matter how short the interval:

$ vmstat 1                         # rates, with scrolling history
$ iostat -x 2                      # per-device I/O rates
$ sar -n DEV 1                     # network rates, and it keeps the history
$ watch -n 1 'cat /sys/class/net/eth0/statistics/rx_bytes'   # a climbing total

The general shape of the rule: watch is excellent at showing you a value, and incapable of showing you a change over time beyond the one-cycle hint that -d gives. Section 7.5 is about the consequences of that.

7. Something Most Users Do Not Know

7.1 A Slow Command Makes watch Lie to You

Section 1.3 showed the interval is a gap. There is a worse version of the same problem, and the manual admits it in the BUGS section rather than hiding it. If the command sometimes takes longer than the interval, watch can end up firing repeatedly to catch up:

BUGS
       --precise mode doesn't yet have advanced temporal distortion technology
       to compensate for a command that takes more than --interval seconds to
       execute.  watch also can get into a state where it rapid-fires as many
       executions of command as it can to catch up from a previous executions
       running longer than --interval (for example, netstat(8) taking ages on
       a DNS lookup).

That is a real hazard when the watched command is expensive. watch -n 1 on a query that usually takes 200ms and occasionally takes four seconds does not politely skip a beat; it can hammer whatever it is querying. Two habits avoid it: set the interval generously above the worst case rather than the typical case, and prefer a cheap proxy for an expensive check. Watching a counter is safer than watching the thing being counted.

7.2 Every Refresh Is a Brand New Process

The PIDs in section 5.1 were not a curiosity, they were the mechanism. Every cycle forks a fresh sh, which forks your command. Nothing carries over between refreshes: no working directory changes, no variables, no shell state at all.

$ watch -t 'echo $$ >> pids.log'
$ cat pids.log
468474
468476
468478
468480                             # a new shell every single time

Three consequences follow. A command with side effects runs those side effects on every refresh, so watch 'curl -X POST ...' is a way to post something several hundred times before lunch. A counter you increment in a variable resets every cycle. And on a short interval you are forking two processes per cycle forever, which is cheap but not free, and is worth remembering before you set -n 0.1 on a busy production box.

7.3 Non-Printing Characters Are Stripped

watch quietly removes control characters from the output rather than passing them through, which is sensible because a stray escape sequence would corrupt the screen it is trying to manage. But it means what you see is not always what the command produced:

$ printf 'a\tb\001c\n' > np.txt      # a, tab, control-A, c
$ cat -A np.txt
a^Ib^Ac$                           # the file really does contain it

# search what reached the terminal for that byte:
$ watch -t cat np.txt
raw 0x01 bytes: 0    visible "^A": 0     # gone without a trace

$ watch -t 'cat -v np.txt'
raw 0x01 bytes: 0    visible "^A": 1     # cat -v turned it into text first

The manual recommends exactly that fix. If you are using watch to hunt down a formatting problem, in a file with odd line endings, in output from a program that is emitting something strange, put cat -v at the end of the pipeline or you will be looking at a cleaned-up version of the evidence.

7.4 watch Is Not a File Watcher

This is the mistake that costs the most time, because watch appears to work. Point it at a build and it does refresh, so nothing looks broken; it is simply doing the wrong job at the wrong moment.

The kernel has an interface for the right job, inotify, and it tells you the instant a file changes instead of up to N seconds later. The tools built on it are the ones you want:

$ ls *.c | entr -c make            # rebuild the instant a source file is saved
$ inotifywait -m -e close_write /var/spool/incoming

The rule of thumb: if the thing you care about emits an event, listen for the event. Use watch for state that nothing announces, which is most of what a server does. Disk usage, connection counts, queue depth and process lists have no notification mechanism, and polling them on a timer is exactly right.

7.5 It Samples, So It Misses Things

watch shows you the present and forgets it immediately. Both halves of that sentence cost people time.

The forgetting comes first. Suppose load on a server does this:

12:00   0.4
12:01   0.5
12:02   8.7        <- the thing you were called about
12:03   0.6

You start watch uptime at 12:03 and see 0.6. Not "0.6, and it was fine before either": just 0.6, with no way to tell the difference between a server that has been calm all morning and one that fell over sixty seconds ago. -d=permanent helps a little from the moment you start, and no further back.

The missing comes second, and it is the more subtle one. Between two refreshes, watch is not looking. Anything shorter than the interval can happen entirely in the gap:

interval:   |-----2s-----|-----2s-----|-----2s-----|
sampled:    X            X            X
the event:        [==1.5s==]                            never seen

Shortening the interval narrows the gap but never closes it, and it costs more on every cycle. That trade is worth stating plainly because it is not specific to watch at all:

short interval   better resolution, more overhead, more load on what you watch
long interval    less overhead, more that happens invisibly between samples

The same trade governs every metrics system, every SNMP poll and every health check you will ever configure. watch is a good place to meet it, because here the cost of getting it wrong is only a confusing screen.

Two habits follow. When you are investigating something intermittent, log it rather than watch it, so there is a record to read afterwards:

$ while true; do printf '%s %s\n' "$(date +%T)" "$(cut -d' ' -f1 /proc/loadavg)"; sleep 5; done | tee load.log

And when you want to know what happened before you arrived, accept that this is not watch's job. Use whatever already kept the history: sar, the journal, your application's own logs, or a monitoring system. watch answers "what is happening now", and only that.

7.6 Colour Became the Default, and It Changed Old Commands

procps-ng 4.0.4 turned on ANSI interpretation by default. The Debian changelog records it in one line:

$ zcat /usr/share/doc/procps/changelog.Debian.gz | grep -i "watch:"
  * watch: Color support turned on by default use -C to turn off

You can see the switch by counting the colour codes that survive:

# command emits ESC[31m for red
$ watch ...        SGR-31 sequences passed through: 1     # interpreted
$ watch -c ...     SGR-31 sequences passed through: 1     # same, -c is now redundant
$ watch -C ...     SGR-31 sequences passed through: 0     # stripped

Mostly this is an improvement. It bites in one specific place: a command whose output you are reading for the escape codes now has them swallowed. If you were using watch to inspect raw coloured output, add -C. And if you find a tutorial insisting you need -c, it was written before 2023 and the rest of its advice may be equally dated.

7.7 Knowing Where watch Stops

watch is a small tool and it is honest about its size. The point where you should stop stretching it:

Before any of those, though, there is a cheaper question to ask, and it is the one people skip: does the command already know how to repeat itself? A surprising number do, and their own mode is almost always better than wrapping them:

Look closely at the second and third rows, because they are not just tidier. vmstat 1 and iostat -x 2 print a new line every interval and let it scroll, which means they give you the two things section 7.5 said watch structurally cannot: rates, and a history you can look back through. When a tool offers its own repeat mode, it usually offers those too.

That fifth row is worth trying if you have tmux already. Three panes running watch -d on disk, connections and queue depth make a serviceable dashboard out of tools you have:

$ tmux new-session -d 'watch -d -n 5 df -h'
$ tmux split-window -h 'watch -d -n 2 "ss -tn state established | wc -l"'
$ tmux split-window -v 'watch -d -n 5 "ls /var/spool/queue | wc -l"'
$ tmux attach

9. Common Mistakes

9.1 watch Versus a Shell Loop

Nearly everyone writes the loop before they learn the command, and the loop is a perfectly reasonable thing to write. It is worth being clear about what you gain and what you give up, because the answer is not "the loop is worse".

$ while true; do clear; df -h; sleep 5; done

That is the honest equivalent, and for a quick look it is fine. Here is what watch -n 5 df -h adds:

The split is clean once you see it. watch is for looking; a loop is for doing. If a human is going to sit and read the screen, watch -d wins on every point that matters. The moment the answer needs to be acted on, logged, retried or returned to a caller, write the loop, because watch cannot pass the result out (section 6.4).

That last row is easy to forget. Dropping the clear turns the loop into something watch cannot do at all: a scrolling record you can page back through afterwards, which section 7.5 argued is often what you actually wanted.

9.2 Myth Versus Reality

9.3 Other Traps to Avoid

• Watching something with side effects. watch 'curl -X POST .../deploy' deploys every two seconds. The same goes for anything with rm, mv, INSERT or an email in it.
• Putting a credential in a watched command. The secret sits in watch's own argument list for the entire session, visible to everyone:

  $ watch -n 2 'mysql -u root -phunter2 -e "SHOW PROCESSLIST"'
  
  # from any other account on the box, for as long as it runs:
  $ ps -ef | grep watch
  pe7er  471478  watch -n 2 mysql -u root -phunter2 -e SHOW PROCESSLIST

  Use a credentials file, a socket, or an environment variable the command reads itself. A one-off command flashes past in the process table; a watch parks it there.
• Watching a command that waits for input. git log, systemctl status and friends open a pager, which then sits there. Add --no-pager, or set PAGER=cat.
• Leaving a short interval running for hours. -n 0.1 is twenty processes a second, forever. Fine for a minute of debugging, rude on a shared server overnight.
• Watching sudo. sudo cannot prompt from inside watch, so unless the credential is already cached every refresh fails the same way: sudo: a password is required. Authenticate first, or start the whole thing with sudo watch ... so the prompt happens once, up front.
• Forgetting the command is re-parsed every cycle. A relative path is resolved against the directory you started in, which is fine, but a cd inside the command does not persist to the next refresh.
• Expecting -d to survive a resize. The manual is explicit: on terminal resize the screen is not repainted until the next update, and all highlighting is lost.
• Using watch as a poor man's monitor. It has no history, no alerting and no record. If it matters at three in the morning, it belongs in a monitoring system.
• Assuming -x is just a tidier way to quote. It removes the shell completely, so pipes, redirects, globs and variables stop working (section 5.3).
• Trusting a screenshot of watch without the header. With -t there is no timestamp, so a stale screenshot looks exactly like a live one.
• Reaching for it on a slow link. Every refresh repaints the whole screen. Over a laggy SSH session a one-second interval is worse than useless; raise the interval and shrink the output.