--- name: "watch" section: "1" platform: "linux" package: "procps-ng" version: "4.0.7-1" release: "Arch Linux 2026-11-01" platforms: ["linux", "openbsd"] url: "https://new.carta.tech/watch" --- # watch(1) execute a program periodically, showing output fullscreen ## NAME watch - execute a program periodically, showing output fullscreen ## SYNOPSIS **watch** \[*option* ...\] *command* ## 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 - **-b**, **--beep** Beep if *command* has a non-zero exit. - **-c**, **--color** Interpret ANSI color and style sequences. - **-C**, **--no-color** Do not interpret ANSI color and style sequences. - **-d**, **--differences**\[=*permanent*\] 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** 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** 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** 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* 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** 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** \ Exit when output of *command* does not change for the given number of cycles. - **-r**, **--no-rerun** 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** Turn off the header normally shown at the top of the screen. - **-w**, **--no-wrap** Turn off line wrapping. Long lines will be truncated instead of wrapped to the next line. - **-x**, **--exec** Pass *command* to an [**exec**(3)](/exec/3.md) 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** Display help text and exit. - **-v**, **--version** Display version information and exit. ## KEY CONTROL - **spacebar** Issue *command* immediately. If it's running at the moment, it is not interrupted and its next round will start without delay. - **q** Quit **watch**. It currently does not interrupt a running *command* (as opposed to terminating signals, such as the SIGKILL following Ctrl+C). - **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 - **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)** With **--errexit** the last exit code of *command* is returned. ## ENVIRONMENT The behavior of **watch** is affected by the following environment variables. - **WATCH\_INTERVAL** Update interval, follows the same rules as the **--interval** command line option. - **COLUMNS** Terminal screen character width. Set to override autodetection. - **LINES** Terminal screen character height. Set to override autodetection. ## 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 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 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 Please send bug reports to ⟨procps@freelists.org⟩.