whatisgithub

What is watchman?

facebook/watchman — explained in plain English

Analysis updated 2026-06-24

★ 13,578C++Audience · developerComplexity · 3/5Setup · moderate

In one sentence

A background service from Meta that monitors files and folders for changes and triggers automated actions, like rebuilding a project or running tests, whenever a file is saved.

Mindmap

mindmap
  root((Watchman))
    What it does
      Detects file changes
      Triggers actions
      No filesystem polling
    Platforms
      Windows
      macOS
      Linux
    Client libraries
      Python
      Rust
      JavaScript
    Common uses
      Build systems
      Test runners
      Dev servers
Click or tap to explore — scroll the page freely

Code map

Detail Auto

An interactive map of this repo's files and how they connect — its source is parsed live in your browser. Click Visualize to build it.

filefunction / class

What do people build with it?

USE CASE 1

Integrate Watchman into a build system to automatically rebuild a project whenever source files change, without polling the filesystem

USE CASE 2

Use the Python client library to trigger a test runner whenever files in a specific directory are modified

USE CASE 3

Connect Watchman to a development server to reload automatically every time you save a file

What is it built with?

C++PythonRustJavaScript

How does it compare?

facebook/watchmanisl-org/open3dapache/incubator-weex
Stars13,57813,58413,632
LanguageC++C++C++
Setup difficultymoderatemoderatehard
Complexity3/53/54/5
Audiencedeveloperresearcherdeveloper

Figures from each repo's GitHub metadata at analysis time.

How do you get it running?

Difficulty · moderate Time to first run · 30min

Typically used as a background infrastructure component integrated into build tools rather than interacted with directly, reading the documentation is needed before standalone use.

So what is it?

Watchman is a service that monitors files and folders on your computer for changes. When a file is modified, created, or deleted, Watchman detects it and can automatically trigger actions in response, such as rebuilding a project, running tests, or reloading a development server. This makes it useful for development workflows where you want things to happen automatically every time you save a file. The project was created at Meta (formerly Facebook) and is maintained by their source control team. It runs on Windows, macOS, and Linux, and includes client libraries for Python, Rust, and JavaScript. Additional platform support and packaging is handled by the broader community. Watchman is a low-level infrastructure component, meaning it is typically used behind the scenes by other developer tools rather than something you interact with directly. Build systems and test runners can use it to watch for file changes and respond quickly without polling the filesystem repeatedly. Full documentation is available at the project's website.

Copy-paste prompts

Prompt 1
Using the Watchman Python client library, write a script that watches a src/ directory for any .py file changes and prints the name and modification time of each changed file
Prompt 2
Set up Watchman to trigger an npm run build command whenever any file inside a src/ folder changes, and show me the watchman-make or trigger configuration needed
Prompt 3
Write a JavaScript script using the Watchman JS client that subscribes to file change events in a project directory and logs each modified file path with a timestamp
Prompt 4
Use the Watchman command-line tool to set up a watch on a directory, query which files have changed since the last check, and output the results as JSON

Frequently asked questions

What is watchman?

A background service from Meta that monitors files and folders for changes and triggers automated actions, like rebuilding a project or running tests, whenever a file is saved.

What language is watchman written in?

Mainly C++. The stack also includes C++, Python, Rust.

How hard is watchman to set up?

Setup difficulty is rated moderate, with roughly 30min to a first successful run.

Who is watchman for?

Mainly developer.

Open on GitHub → Ask about another repo

This repo across BitVibe Labs

Verify against the repo before relying on details.

What are similar repos?