# Watchman: a daemon that records when files actually change, not when they appear to

> Meta's Watchman is a file watching service with a long compatibility commitment and clients in Python, Rust and JavaScript. Its README is a pointer rather than a manual, so most of the evaluation has to happen on the documentation site.

**facebook/watchman** — Watches files and records, or triggers actions, when they change. 

- Repository: https://github.com/facebook/watchman
- Website: https://facebook.github.io/watchman/
- Stars: 13,735 · Forks: 1,069
- Language: C++
- License: MIT
- Published: 2026-10-06 · Updated: 2026-10-06 · Language: en
- Canonical page: https://hysenlabs.com/projects/facebook-watchman

## Recording change events rather than trusting notifications

The README states the purpose in two sentences and both halves matter. Watchman exists to watch files and record when they actually change, and it can also trigger actions, such as rebuilding assets, when matching files change.

The word "actually" in that first sentence is the design position. A tool that registers for filesystem notifications and reacts to each one has to assume the notification is complete and accurate. On a real machine neither holds: editors write through temporary files and rename them into place, build tools touch files without changing content, version control checkouts replace directories wholesale, and network filesystems deliver notifications late, duplicated or not at all. A watcher built on that assumption spends its life deduplicating and re-checking.

Watchman's approach is to be the authority on what changed, not merely a forwarder of events. Something upstream that needs to know whether a set of paths differs from a previous state asks Watchman, and the answer is recorded state rather than a stream to interpret. That is why the project describes itself as a service rather than a library, and it is the reason its interface is a client protocol with bindings in several languages instead of a header you include.

The consequence for a reader evaluating it: Watchman is infrastructure with a lifetime, a socket and a query language. If your tool needs to know what changed on disk, this is a well-supported way to find out. If your tool only needs to notice that one file you are editing was written, it is a very large answer to a small question.

## A support matrix split between Meta and the community

The README is unusually clear about who owns what, which is more than most projects bother with. Watchman is primarily maintained by the source control team at Meta Platforms, and the supported list covers Windows and macOS builds, Linux builds on recent Ubuntu and Fedora releases, a documented compatibility commitment, and clients for Python, Rust and JavaScript.

Everything else is labelled community-maintained: Homebrew packaging, FreeBSD, and Solaris. That labelling does real work for an adopter, because it tells you that `brew install watchman` is not the same risk as a release artefact, and that a FreeBSD port will lag the supported platforms rather than break them.

The compatibility commitment deserves separate attention and has its own page in the documentation. A file watching service sits in the middle of everyone else's build, so the interesting question is not whether version 2026.09 works but whether the version you deploy can still talk to the clients you have written and whether a configuration file from an older release is still valid. A published commitment on that subject is the kind of thing you look for precisely when you are considering putting a daemon between a developer and their build.

Troubleshooting is routed to GitHub issues, and contributions go through the `CONTRIBUTING.md` document at the repository root.

## Three first class clients and what that implies

The supported client list is Python, Rust and JavaScript, and the choice of those three says something about intended consumers. Python is the scripting language of build systems and test harnesses, so a Python client covers the common case of wiring change detection into an existing build tool. Rust suits a tool that wants Watchman's state without taking on a C++ dependency, which is the common situation for a modern CLI. JavaScript covers editor integrations and web tooling.

What all three share is that they are clients rather than in-process libraries. A client talks to a running service, which means the service needs to be installed, started, and kept running, and that there is a version compatibility question between client and server. This is the operational tax that comes with the accuracy benefit, and it is the single most important thing to understand before adopting Watchman.

The contrast with the usual alternatives is instructive. Polling a directory tree on an interval needs no daemon and no client library, but it costs you a full traversal per tick and cannot tell content change from timestamp change. Listening to `inotify` on Linux directly needs no daemon, but it requires writing the edge-case handling yourself and it is platform specific, which is exactly the problem the cross-platform support matrix exists to solve. Watchman takes the correctness work and turns it into something you install.

So the honest framing is that Watchman trades a service dependency for correctness and portability. Whether that trade pays depends on how much of your build time is currently spent on watchers that report the wrong thing.

## Weekly release tags with no changelog bodies

The release history is a series of date-based tags on a weekly cadence: v2026.09.21.00, v2026.09.14.00 and v2026.09.07.00 are all present, each about seven days apart and each carrying the pattern of a build number after the date. The repository is not archived and the last push was on 2026-09-21, matching the newest tag.

There is something to notice in what the release notes do not contain: the bodies for these three releases are empty. That is typical of infrastructure projects that tag continuously and keep the change narrative somewhere else, most likely in the commit history and the pull request stream rather than in GitHub releases. It does mean you cannot answer "what changed in this version" from the releases page alone.

For a service, the date-based scheme is a feature rather than a naming quirk. Watchman's identity is tied to its notion of current state, and a version string that encodes the build date makes it straightforward to talk about whether two Watchman instances agree, whether a client matches its server, and whether a bug report can be tied to a specific build.

The MIT licence is stated in the README and spelled out in the LICENSE file, which is the permissive default and means no obligations beyond attribution and notice when you vendor it internally.

## The repository layout points to a build with two toolchains

The top-level tree explains more about the project than the README does, and two things stand out. First, the build has both a Unix and a Windows entry point, `autogen.sh` alongside `autogen.cmd`, backed by a `CMakeLists.txt` at the root and a `build/` directory. There is also `install-system-packages.sh` and `run-tests.sh`, which is the shape of a project whose Windows and Unix builds are expected to work from a fresh clone.

Second, `clippy.toml` and `rustfmt.toml` sit at the root next to the C++ build files. Watchman is described as C++, and the bulk of the service is, but the presence of Rust lint and format configuration alongside the officially supported Rust client says the Rust code is in this repository rather than merely talked to over a socket. If you are picking a language to extend Watchman in, the repository suggests both are live options.

The `eden/` directory is the third entry worth noting. Whatever it contains, it is a first class top-level component rather than an experiment, and its presence is a reminder that Watchman is tightly coupled to how Meta does source control at scale, which is both the source of its design decisions and the reason it does not obviously generalise to every kind of file tree.

The documentation site lives in `website/`, matching the published site, and the logo asset is under `website/static/img/`.

## Where the README stops and the documentation takes over

This is the honest limitation of evaluating Watchman from its repository page. The README is a short pointer: a logo, a purpose statement in two sentences, a link to facebook.github.io/watchman, the support split, and the contribution and issue routes. There is no install command in it, no configuration reference, no query language example and no API listing.

Everything you would need for a real decision is on the documentation site, and the README is candid enough to say so in one line: head on over to the site. The linked pages visible from the README are the compatibility commitment and the contributing document, and the site root is the entry point for the rest.

That structure has a consequence worth naming. You cannot scope Watchman from the README alone, so any evaluation has to include time with the docs. What you can learn cheaply from the repository is the shape of the thing: a service with a compatibility promise, three first class clients, a weekly release train, a permissive licence, and a maintained platform list. What you cannot learn cheaply is whether its query language fits your build system's access pattern, or how its configuration handles the tree layout you have.

If your decision hinges on those two questions, the compatibility document and the query language reference are the two pages to read first, because they decide whether the accuracy this service buys you is available for your tree layout at all.

## Conclusion

Watchman is worth the daemon when a build or indexer has to react correctly to large trees, because recording real change events rather than trusting filesystem notifications is the problem it was built to solve, and the Python, Rust and JavaScript clients plus the documented compatibility commitment make it adoptable as infrastructure rather than a library you vendor. It is the wrong choice for a single-repository tool where an in-process watcher or an IDE's own watcher is already good enough, since a background service is a thing that can be stale, killed or out of sync with your checkout. The repository ships `autogen.sh`, `CMakeLists.txt` and `run-tests.sh` for building, the last push was on 2026-09-21, and releases are tagged weekly, so start by reading the compatibility document and the query language reference on facebook.github.io before choosing a configuration.

## FAQ

### What does Watchman do?

Watchman watches files and records when they actually change, and it can trigger actions such as rebuilding assets when matching files change. It is a service with clients rather than an in-process library, so it keeps state that callers query.

### Which platforms does Watchman support?

Meta maintains Windows and macOS builds, Linux builds on recent Ubuntu and Fedora releases, and clients for Python, Rust and JavaScript. Homebrew packaging, FreeBSD and Solaris are community-maintained rather than supported directly.

### Which programming language clients does Watchman have?

The supported clients are Python, Rust and JavaScript. All of them talk to a running Watchman service over its client protocol, so a version match between client and server matters.

### What license is Watchman released under?

Watchman is made available under the terms of the MIT License, and the README directs readers to the LICENSE file that accompanies the distribution for the full text.

### How often is Watchman released?

Releases follow a weekly, date-based tagging scheme, for example v2026.09.21.00 and v2026.09.14.00. The repository is not archived and the last push was on 2026-09-21, so the release train is still running.

## Sources

- [facebook/watchman on GitHub](https://github.com/facebook/watchman)
- [License: MIT](https://github.com/facebook/watchman/blob/main/LICENSE)
- [Project website](https://facebook.github.io/watchman/)
- [README](https://github.com/facebook/watchman/blob/main/README.md)
- [Releases](https://github.com/facebook/watchman/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/facebook-watchman