Skip to content
Get packs

Guide · Open source

How to use watchman: install, watch files and trigger actions

Updated · written with AI from the project's own documentation and checked against our catalogue data

Watchman is an open-source file-watching service from Meta that monitors directories and notices when files are created, changed, or deleted. This guide explains what it does, how to get the source code, and when it is the right tool. The source available for this entry is short, so the steps below stick to what it confirms and point out where you will need the project's full documentation.

Watchmanmeta/watchman · ★ 13.8k · MIT

Quick start

  1. 1Check your fit. Confirm you need ongoing change detection, not a one-off search.
  2. 2Clone the repository. Run the git clone command for meta/watchman from GitHub.
  3. 3Read the build docs. Open the repository README and the homepage at facebook.github.io/watchman for build steps.
  4. 4Build from source. Follow the project's clone-and-build instructions for your system.
  5. 5Start the service. Launch Watchman and register the directories you want it to watch, as the official docs describe.
  6. 6Connect your action. Hook a build, test, or notifier to the change events Watchman reports.

What Watchman does

Watchman runs as a service that watches the directories you point it at. When a file is created, changed, or deleted, it notices the change. It can then run an action or report the change to a program that asked for it.

This makes it useful when you want work to happen automatically as code changes, rather than scanning folders over and over to find out what is new.

  • Watches directories for created, changed, and deleted files
  • Can run an action in response to a change
  • Can report changes to a requesting program

Get the Watchman source code

The repository is hosted on GitHub under the meta organisation. Cloning it is the first step. The source entry lists no prerequisites, so check the project's own documentation for what your system needs before building.

git clone https://github.com/meta/watchman

Build and run Watchman

The install method for this project is clone-and-build. The source available here does not include the build steps or the commands to start the service, because the README was unavailable when this entry was written.

Follow the build instructions in the repository and the project homepage at https://facebook.github.io/watchman/. Those documents are the authoritative source for compiling, starting the service, and registering directories to watch.

Decide whether Watchman fits your project

Watchman is built for ongoing watching. It suits developers who want to run a build or test when source files change, teams whose tools need fast and reliable notifications about file changes, and developers in large codebases where repeatedly scanning directories is slow.

It is not the best choice for a one-off file search, and it is not a point-and-click app. The source does not describe a graphical interface.

  • Good fit: rebuild or retest on source changes
  • Good fit: tools that need reliable change notifications
  • Good fit: large codebases where directory scans are slow
  • Poor fit: one-time file search
  • Poor fit: anyone wanting a graphical app

What people use it for

  • Re-running a build or test when source files change
  • Sending reliable file-change notifications to other tools
  • Watching large codebases without repeatedly scanning every directory

Frequently asked questions

Is Watchman free to use?

Yes. Watchman is released under the MIT licence, which is a permissive open-source licence. Check the LICENSE file in the repository for the full terms.

What language is Watchman written in?

Watchman is written in C++. You will need a C++ toolchain to build it from source.

What are the requirements to install Watchman?

The source entry lists no prerequisites. Consult the repository README and the official homepage for your operating system's requirements before building.

How do I install Watchman?

Clone the repository with git clone https://github.com/meta/watchman, then build it from source following the project's documentation.

Does Watchman have a graphical interface?

The available source does not describe a graphical interface. Treat Watchman as a command-line and service tool unless the official docs say otherwise.

What can I use instead of Watchman?

This entry lists no comparable projects. For simple cases, a scheduled scan or a general file-watcher library may be enough, but this source does not compare them to Watchman.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Watchman suits developers and teams who need ongoing, reliable file-change detection, especially in large codebases. If you only need a one-off file search or a point-and-click app, pick a different tool. Because the README was unavailable for this entry, read the official documentation before you build.

Install options & downloads