What is watchman, and why is it using CPU on my Mac?
Last reviewed: 19 November 2026. Commands checked against Watchman's documentation.
watchman is a file watching service from Meta that developer tools such as Jest use to learn quickly which files changed. It keeps watching the project folders those tools registered, even after the tools exit, and it uses CPU when many files change or when it has to recrawl a whole folder. Listing and removing old watches, or shutting down the server, stops that work.
watchman at a glance
| watchman | |
|---|---|
| Made by | Meta (open source) |
| Type | File watching service |
| Runs as | your user |
| Can you quit it? | Yes. Tools that use it start it again and rebuild their watches, which costs a full crawl. |
What is watchman?
Watchman's documentation describes it as a file watching service that records changes and can trigger actions when matching files change. Tools connect to the watchman server, ask it to watch a project root, and then query it for changes instead of scanning the disk themselves. Jest's configuration, for example, has a watchman option that defaults to true.
On macOS, watchman receives changes through FSEvents, the system's file event service. It is usually installed with brew install watchman. Watches persist across restarts of the server unless they are removed.
Is watchman safe?
Yes, when you or a development tool installed it. It reads file metadata in the folders it was asked to watch.
Why does watchman use so much CPU and memory?
- Many files changing. Installing packages, switching branches or running a build in a watched folder produces many file events for watchman to process.
- Recrawls. When the event stream drops events, watchman recrawls the whole tree. Its troubleshooting guide says recrawls are costly, and on macOS the message kFSEventStreamEventFlagUserDropped indicates the system limit was exceeded.
- Old watches on large folders. Every root a tool ever asked it to watch stays watched until removed, so old projects with large
node_modulesfolders add memory and work. - Overlapping watches. Watching a folder and also a folder inside it, or several tools watching the same tree, multiplies the work.
How much CPU is normal for watchman?
Near 0% CPU when nothing changes in the watched folders. Bursts during installs, checkouts and builds are expected.
Its memory grows with the number of files in the watched roots.
How do you reset watchman when it uses too much CPU?
- See what it watches. Run
watchman watch-listto print the folders it is watching. - Remove watches you do not need. Run
watchman watch-del /path/to/folderfor each old project; this removes the watch and its triggers. - Reset everything. Run
watchman watch-del-alland thenwatchman shutdown-server. Tools re-create the watches they need on their next query. - Reduce dropped events. If recrawl warnings mention kFSEventStreamEventFlagUserDropped, the troubleshooting guide suggests raising
fsevents_latencyin the project's.watchmanconfig.
When should you worry about watchman?
Constant CPU with nothing changing usually means repeated recrawls. Check the watchman log and the recrawl warnings that tools such as Jest print.
If you no longer use Jest or another tool that needs it, watchman shutdown-server stops it.
How do you check watchman in Activity Monitor and Terminal?
Open Activity Monitor (Applications > Utilities), and type watchman in the search field. The CPU tab shows its % CPU. The Memory tab shows its Memory. Double-click the row for its parent process, memory details and open files.
In Terminal, the first command lists every watchman process with its PID, user, CPU and memory (RSS is resident memory in kilobytes).
ps -axo pid,user,%cpu,%mem,rss,command | grep -F 'watchman' | grep -v grep
How can Thrum help with watchman?
Thrum keeps a live CPU graph in the menu bar. One click shows the eight processes using the most CPU, so you can see when watchman is among them and how much it takes. An optional alert tells you when a process stays above a CPU level you choose (50 to 200% of one core) for 1 to 10 minutes. Click watchman in the list for its PID, threads and memory, and Quit or Force Quit it after a confirmation.
Thrum is $4.99 once with a 14-day free trial and no account. It requires macOS 26 Tahoe on Apple silicon or Intel.
Questions about watchman
Why is watchman still running after I closed my project?
The server stays running and keeps its watches so the next query is fast. watchman shutdown-server stops it.
Is watchman related to fseventsd?
watchman uses macOS's FSEvents to learn about changes, and fseventsd is the system process behind FSEvents. Heavy file activity can make both busy at once.