This post was originally published on go2linux.org. The domain is no longer mine, but I am the original author. I am republishing it here on garron.me with corrections and improvements.

watch runs a command over and over and shows its output full screen, so you can see it change without retyping the command. Press Ctrl+C to quit.

Basic usage

watch [options] command

With no options the command runs every 2 seconds:

watch free -h

The header line shows the interval, the command, the hostname and the current time.

Change the interval

Use -n with the number of seconds:

watch -n 5 free -h

Fractions are accepted, down to 0.1 seconds:

watch -n 0.5 date

Highlight what changed

-d highlights the differences between one update and the next:

watch -d free -h

The highlight lasts for one refresh. To keep highlighted everything that has changed since the first run, use -d=permanent:

watch -d=permanent ls -l /var/log

Older versions of watch documented this value as cumulative.

Pipes and quotes

This is the most common mistake with watch:

watch ps aux | grep nginx

Here the shell pipes the output of watch itself into grep, which is not what you want. Quote the whole pipeline so watch runs it:

watch 'ps aux | grep nginx'

Use single quotes when the command contains $ variables or command substitutions that must be evaluated on every run, not once when you press Enter:

watch 'echo $(date +%s)'

Hide the header

-t removes the header line, which gives a cleaner screen and one more line of output:

watch -t date

Exit when the output changes

-g makes watch exit as soon as the output differs from the previous run. That turns it into a simple "wait until" tool:

watch -g 'ls /mnt/backup' && echo "backup directory changed"

Wait for a file to appear or grow, then continue with the next command:

watch -g -n 10 'stat -c %s dump.sql' ; notify-send "dump is moving"

React to errors

-b beeps when the command exits with a non-zero status. -e freezes the screen on the error and exits after a key press:

watch -e -n 30 'curl -fsS -o /dev/null https://www.example.com'

As long as the site answers, the screen stays empty. On the first failure watch stops and shows the error.

Keep colors

Many commands turn colors off when they are not writing to a terminal, and watch strips escape sequences by default. Force color in the command and add -c so watch interprets it:

watch -c 'ls --color=always -l'

Aliases do not work inside watch

watch runs the command with sh -c, which knows nothing about your Bash aliases. watch ll fails even if ll works at the prompt. Either type the real command, or define this alias — the trailing space makes Bash expand the word that follows:

alias watch='watch '

Practical examples

Disk space while a large copy runs:

watch -d df -h /home

The ten processes using the most memory:

watch -n 5 'ps aux --sort=-%mem | head -n 11'

Listening ports:

watch -n 2 'ss -tulpn'

Number of connections to a web server:

watch -n 1 'ss -tn state established "( sport = :443 )" | wc -l'

RAID rebuild progress:

watch -n 10 cat /proc/mdstat

The while-loop alternative

watch clears the screen on every run. When you want the results one after another so you can scroll back or save them, use a loop:

while true; do date; free -h | grep Mem; sleep 5; done

Add | tee -a memory.log after done to keep a copy.

See also

man watch — full reference.