WATCH(1) General Commands Manual WATCH(1)

# [NAME](#NAME)

watch - execute a program periodically, showing output fullscreen

# [SYNOPSIS](#SYNOPSIS)

**watch** \[*option* ...] *command*

# [DESCRIPTION](#DESCRIPTION)

**watch** runs *command* repeatedly, displaying its output and errors (the first screenful). This allows you to watch the program output change over time. By default, *command* is run every 2 seconds and **watch** will run until interrupted. A header informs of the start and running time of *command* as well as its exit code.

# [OPTIONS](#OPTIONS)

[**-b**, **--beep**](#b)

Beep if *command* has a non-zero exit.

[**-c**, **--color**](#c)

Interpret ANSI color and style sequences.

[**-C**, **--no-color**](#C)

Do not interpret ANSI color and style sequences.

[**-d**, **--differences**\[=*permanent*\]](#d)

Highlight the differences between successive updates. If the optional *permanent* argument is specified then **watch** will show all changes since the first iteration. The *permanent* argument needs to be linked to the option, such as **-d1** or **--differences=1**.

[**-e**, **--errexit**](#e)

Freeze updates on *command* error, and exit after a key press. The exit code of **watch** will be the code *command* exits with. If signal **n** is the cause of *command* termination, the exit code will be 128 + **n**.

[**-f**, **--follow**](#f)

Instead of clearing the screen at each update, **watch** will scroll the output similar to how *tail -f* works. This option is not compatible with any option tracking the output of the screen, such as the **--differences**, **--chgexit** and **--eqexit** options.

[**-g**, **--chgexit**](#g)

Exit when the visible output of *command* changes. Changes that are off the screen due to small screen size or large output will not cause **watch** to exit.

[**-n**, **--interval** *seconds*](#n)

Specify update interval. Values smaller than 0.1 and larger than 2678400 (31 days) are converted into these respective bounds. Both '.' and ',' work for any locale. The **WATCH\_INTERVAL** environment variable can be used to persistently set a non-default interval (following the same rules and formatting).

[**-p**, **--precise**](#p)

Execute *command* **--interval** seconds after its previous run started, instead of **--interval** seconds after its previous run finished. If it's taking longer than **--interval** seconds for *command* to complete, it is waited for in either case.

**-q**, **--equexit** <cycles>

Exit when output of *command* does not change for the given number of cycles.

[**-r**, **--no-rerun**](#r)

Do not run the program on terminal resize, the output of the program will re-appear at the next regular run time.

**-s**, **--shotsdir**

Directory to save screenshots into.

[**-t**, **--no-title**](#t)

Turn off the header normally shown at the top of the screen.

[**-w**, **--no-wrap**](#w)

Turn off line wrapping. Long lines will be truncated instead of wrapped to the next line.

[**-x**, **--exec**](#x)

Pass *command* to an [**exec**(3)](/man/os/procps/exec.3) call instead of **sh -c**. The program will start a bit quicker. Shell features (environment setup, variable and pathname expansion, etc.) will be unavailable.

[**-h**, **--help**](#h)

Display help text and exit.

[**-v**, **--version**](#v)

Display version information and exit.

# [KEY CONTROL](#KEY_CONTROL)

[**spacebar**](#spacebar)

Issue *command* immediately. If it's running at the moment, it is not interrupted and its next round will start without delay.

[**q**](#q)

Quit **watch**. It currently does not interrupt a running *command* (as opposed to terminating signals, such as the SIGKILL following Ctrl+C).

[**s**](#s)

Take a screenshot. It will be saved in the working directory, unless specified otherwise by **--shotsdir**. If *command* is running at the moment, the screenshot will be taken as soon as it finishes.

# [EXIT STATUS](#EXIT_STATUS)

**0**

Success. Does not represent *command* exit code.

**1**

Errors unrelated to *command* operation.

**2**

Errors related to *command* execution and management (not its exit code).

[**any non-zero (--errexit)**](#any)

With **--errexit** the last exit code of *command* is returned.

# [ENVIRONMENT](#ENVIRONMENT)

The behavior of **watch** is affected by the following environment variables.

[**WATCH\_INTERVAL**](#WATCH_INTERVAL)

Update interval, follows the same rules as the **--interval** command line option.

[**COLUMNS**](#COLUMNS)

Terminal screen character width. Set to override autodetection.

[**LINES**](#LINES)

Terminal screen character height. Set to override autodetection.

# [NOTES](#NOTES)

POSIX option processing is used (i.e., option processing stops at the first non-option argument). This means that flags after *command* don't get interpreted by **watch** itself.

Non-printing characters are stripped from program output. Use **cat -v** as part of the command pipeline if you want to see them.

# [EXAMPLES](#EXAMPLES)

To watch the contents of a directory change, you could use

watch -d ls -l

If you have CPUs with a dynamic frequency and want to observe it change, try the following. The command is passed to the shell, which allows you to make the pipeline. The quotes are a feature of the shell too.

watch -n1 'grep "^cpu MHz" /proc/cpuinfo | sort -nrk4'

To monitor the up status of your servers, saving a copy of the output of each run to a file, you may use this. The **-p** makes the command execute every 10 seconds regardless of how long it took to complete the previous run.

watch -n10 -p -d '{ date; for i in 10.0.0.31 10.0.0.32 10.0.0.33; do R=OK; ping -c2 -W2 "$i" &>/dev/null || R=FAIL; echo "$i: $R"; done } | tee -a ~/log'

You can watch for your administrator to install the latest kernel with

watch uname -r

# [BUGS](#BUGS)

When the terminal dimensions change, its contents changes are not registered on the next *command* run. **--chgexit** will not trigger that turn and the counter of **--equexit** will not restart even if *command* output changes meanwhile. **--differences** highlighting is reset.

# [REPORTING BUGS](#REPORTING_BUGS)

Please send bug reports to [procps@freelists.org](mailto:procps@freelists.org).

2025-04-16 procps-ng

---

Document: watch(1) from procps 4.0.7-r2 (Chainguard OS)
Source: https://downloads.sourceforge.net/project/procps-ng/Production/procps-ng-4.0.7.tar.xz