The watch command

The watch command is useful when you want your book to be rendered on every file change. You could repeatedly issue mdbook build every time a file is changed. But using mdbook watch once will watch your files and will trigger a build automatically whenever you modify a file; this includes re-creating deleted files still mentioned in!

Specify a directory

The watch command can take a directory as an argument to use as the book’s root instead of the current working directory.

mdbook watch path/to/book


When you use the --open (-o) option, mdbook will open the rendered book in your default web browser.


The --dest-dir (-d) option allows you to change the output directory for the book. Relative paths are interpreted relative to the book’s root directory. If not specified it will default to the value of the key in book.toml, or to ./book.


There are different backends used to determine when a file has changed.

  • poll (default) — Checks for file modifications by scanning the filesystem every second.
  • native — Uses the native operating system facilities to receive notifications when files change. This can have less constant overhead, but may not be as reliable as the poll based watcher. See these issues for more information: #383 #1441 #1707 #2035 #2102

Specify exclude patterns

The watch command will not automatically trigger a build for files listed in the .gitignore file in the book root directory. The .gitignore file may contain file patterns described in the gitignore documentation. This can be useful for ignoring temporary files created by some editors.

Note: Only .gitignore from book root directory is used. Global $HOME/.gitignore or .gitignore files in parent directories are not used.