Watchman Watches Your Files So You Don't Have To
You've been there: you save a file, then manually run your build, then refresh your browser, then wonder why nothing changed because you forgot to save a different file. It's a small friction that adds up over a day of development. Watchman exists to watch your files and record when they actually change—and it can trigger actions when matching files change, too.
What It Does
Watchman is a file watching service. Its stated purpose is straightforward: watch files and record when they actually change. Beyond just detecting changes, it can trigger actions—things like rebuilding assets—when files matching certain criteria change.
It's maintained primarily by the source control team at Meta Platforms, Inc., which gives you a sense of the scale it was built to handle. The project supports Windows, macOS, and Linux builds on recent Ubuntu and Fedora releases. There are also Python, Rust, and JavaScript clients available, so you're not locked into a single language ecosystem when integrating it into your tooling.
The README points to the full documentation at facebook.github.io/watchman, and the project ships under the MIT License. Support for Homebrew, FreeBSD, and Solaris is community-maintained, while the core team commits to a compatibility policy and official builds for the major platforms.
Why It's Cool
-
It's built for real workloads, not just toy projects. The fact that Meta's source control team maintains this tells you something. Watching files sounds simple until you're dealing with a monorepo containing hundreds of thousands of files. Watchman was designed to handle that reality, and the compatibility commitment suggests they take stability seriously for people who depend on it in production workflows.
-
Trigger actions, don't just observe. Plenty of tools will tell you a file changed. Watchman goes further by letting you trigger actions when matching files change. That means you can wire it into your build pipeline and let it handle the "rebuild assets" step automatically. It's the difference between a notification and an automation.
-
Multi-language clients mean flexibility. Python, Rust, and JavaScript clients are officially supported. Whether you're writing a build tool, an editor plugin, or a custom dev server, you can talk to Watchman in whatever language makes sense for your project. That's a thoughtful design decision that lowers the barrier to integration.
-
MIT licensed and actively maintained. The license is permissive, which matters if you're considering it for commercial or internal tooling. And with Meta backing it, you're not betting on an abandoned side project.
-
Community support where it counts. The README is honest about what's officially supported versus community-maintained. Homebrew, FreeBSD, and Solaris fall into the latter category. That transparency is useful—you know exactly what you're getting and where to file issues.
How to Try It
Getting started depends on your platform and preferred language client, but the README points you to the official documentation for installation and usage details.
- Head to the documentation at https://facebook.github.io/watchman/ for installation instructions and API references.
- Check the compatibility page if you're planning to integrate it into an existing toolchain—it outlines what the team commits to supporting.
- Pick your client language. Python, Rust, and JavaScript are officially supported, so you can start with whichever fits your stack.
- If you run into trouble, the README asks you to submit a GitHub issue at https://github.com/facebook/watchman/issues/.
The repository itself is at https://github.com/facebook/watchman. If you're contributing, there's a contributing document linked from the README that covers the process.
For Homebrew users on macOS, that installation path is community-maintained, so you'll want to check the docs for the current recommended approach rather than assuming a simple brew install will always be the answer.
Final Thoughts
Watchman isn't flashy. It's infrastructure—the kind of tool you set up once and then forget about because it just works in the background. That's a compliment. If you're building developer tooling, working on a large codebase, or just tired of manually kicking off builds every time you save a file, it's worth a look. The official support for Windows, macOS, and recent Linux distributions covers most developers, and the multi-language clients make it easy to adopt without rewriting your stack. It's a mature, well-maintained project from a team that clearly understands the problem space. Start with the docs, pick your client, and let it handle the watching for you.
Follow @githubprojects for more developer tools and open source projects.