#watcher #inotify #fsevents #kqueue

bin+lib watchexec

Executes commands in response to file modifications

29 stable releases

1.14.0 Jul 3, 2020
1.12.0 Nov 19, 2019
1.10.3 Jul 30, 2019
1.10.1 Feb 18, 2019
1.5.0 Nov 23, 2016

#23 in Command line utilities

Download history 790/week @ 2020-04-22 855/week @ 2020-04-29 803/week @ 2020-05-06 936/week @ 2020-05-13 903/week @ 2020-05-20 787/week @ 2020-05-27 1456/week @ 2020-06-03 1005/week @ 2020-06-10 1056/week @ 2020-06-17 967/week @ 2020-06-24 1263/week @ 2020-07-01 857/week @ 2020-07-08 960/week @ 2020-07-15 816/week @ 2020-07-22 854/week @ 2020-07-29 791/week @ 2020-08-05

4,163 downloads per month
Used in 4 crates (2 directly)




Build status Crates.io status Docs status

Software development often involves running the same commands over and over. Boring!

watchexec is a simple, standalone tool that watches a path and runs a command whenever it detects modifications.

Example use cases:

  • Automatically run unit tests
  • Run linters/syntax checkers


  • Simple invocation and use
  • Runs on OS X, Linux, and Windows
  • Monitors current directory and all subdirectories for changes
    • Uses most efficient event polling mechanism for your platform (except for BSD)
  • Coalesces multiple filesystem events into one, for editors that use swap/backup files during saving
  • By default, uses .gitignore and .ignore to determine which files to ignore notifications for
  • Support for watching files with a specific extension
  • Support for filtering/ignoring events based on glob patterns
  • Launches child processes in a new process group
  • Sets the following environment variables in the child process:
    • If a single file changed (depending on the event type):
      • $WATCHEXEC_CREATED_PATH, the path of the file that was created
      • $WATCHEXEC_REMOVED_PATH, the path of the file that was removed
      • $WATCHEXEC_RENAMED_PATH, the path of the file that was renamed
      • $WATCHEXEC_WRITTEN_PATH, the path of the file that was modified
      • $WATCHEXEC_META_CHANGED_PATH, the path of the file whose metadata changed
    • If multiple files changed:
      • $WATCHEXEC_COMMON_PATH, the longest common path of all of the files that triggered a change
    • This can be disabled or limited with --no-environment and --no-meta
  • Optionally clears screen between executions
  • Optionally restarts the command with every modification (good for servers)
  • Does not require a language runtime


  • Not tied to any particular language or ecosystem
  • Does not require a cryptic command line involving xargs

Usage Examples

Watch all JavaScript, CSS and HTML files in the current directory and all subdirectories for changes, running make when a change is detected:

$ watchexec --exts js,css,html make

Call make test when any file changes in this directory/subdirectory, except for everything below target:

$ watchexec -i target make test

Call ls -la when any file changes in this directory/subdirectory:

$ watchexec -- ls -la

Call/restart python server.py when any Python file in the current directory (and all subdirectories) changes:

$ watchexec -e py -r python server.py

Call/restart my_server when any file in the current directory (and all subdirectories) changes, sending SIGKILL to stop the child process:

$ watchexec -r -s SIGKILL my_server

Send a SIGHUP to the child process upon changes (Note: with using -n | --no-shell here, we're executing my_server directly, instead of wrapping it in a shell:

$ watchexec -n -s SIGHUP my_server

Run make when any file changes, using the .gitignore file in the current directory to filter:

$ watchexec make

Run make when any file in lib or src changes:

$ watchexec -w lib -w src make



watchexec requires Rust 1.38 or later. You can install it using cargo:

$ cargo install watchexec

OS X with Homebrew

$ brew install watchexec


For now, use the GitHub Releases tab to obtain the binary. PRs for packaging in unsupported distros are welcomed.


A deb package is available for amd64 architectures in the GitHub Releases.

Arch Linux

Available in the community repository:

$ pacman -S watchexec


Available using scoop:

#> scoop install watchexec

Or chocolatey:

#> choco install watchexec

Or just unzip the binary from the GitHub Releases.

Shell completions

Currently available shell completions:

  • zsh: completions/zsh should be installed to /usr/share/zsh/site-functions/_watchexec


Rust 1.38 or later is required.


  • notify for doing most of the heavy-lifting
  • globset for super-fast glob matching


~109K SLoC