---
id: pywatchman
version: "4.0.0"
license: The following license applies to all files within this directory and any subdirectories: Copyright 2014-present Meta Platforms, Inc. All rights reserved. Redistribution and use in source and binary… (full text in the JSON record)
license_treatment: permissive
maintenance: active
---

# pywatchman — Watchman client for Python

License: permissive · Maintenance: active · Downloads: 493.2K/mo

## What it is and what it does

pywatchman is a Python client library for interacting with Watchman, Meta's file watching service. It provides a programmatic interface to monitor filesystem changes across Windows, macOS, and Linux. The package itself has no runtime dependencies and is maintained by Meta's source control team.

Watchman watches files and records when they change, then can trigger actions like rebuilding assets in response. The Python client lets developers integrate file-watching capabilities into build systems, development tools, and automation scripts. It supports modern Python versions and is marked as production-stable.

Use it for:

- Integrate file watching into build systems to trigger asset rebuilds when source files change
- Monitor project directories in development tools to detect when to re-run tests or linters
- Watch for filesystem changes in automation scripts that need to react to file modifications
- Build file-change-triggered workflows in IDEs or editor plugins via the Watchman service

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

pywatchman is a Python client for Watchman, a file watching service that monitors filesystem changes and can trigger actions when matching files change.

Yes, if you need file-watching capabilities and are willing to manage the Watchman daemon separately. The client itself is stable, permissively licensed, actively maintained, and has no dependency overhead. Verify that Watchman is available on your target platform and that you understand the daemon-vs-client architecture before committing.

## Install

pip install pywatchman
uv add pywatchman
poetry add pywatchman

## Installing pywatchman

Before you install: Medium install friction due to platform-specific wheels (macOS arm64 binaries provided); no runtime dependencies. Active maintenance with recent release 63 days ago and ongoing repository activity.

License in practice: Permissive BSD-style license (with portions under MIT from the 'six' project) allows commercial and private use with attribution; no copyleft restrictions.

Quickstart:

pip install pywatchman

import pywatchman

client = pywatchman.client()
result = client.query('watch-project', '/path/to/watch')

Requires Watchman daemon to be installed and running on the system; pywatchman is only the client library.

Verify before relying:

- Whether Watchman daemon must be installed separately on the system for pywatchman to function
- Supported platforms beyond the macOS arm64 wheels shown in friction evidence
- Whether this is a pure Python client or requires compiled components on other platforms

## Package facts

- License: The following license applies to all files within this directory and any subdirectories: Copyright 2014-present Meta Platforms, Inc. All rights reserved. Redistribution and use in source and binary… (full text in the JSON record) (permissive)
- Python support: supports_current
- Install friction: medium
- Maintenance: active
- Downloads: 493.2K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

file system watcher, filesystem change detection, watchman python client, file monitoring service, trigger actions on file changes, inotify fsevents wrapper, watch directory for changes, file-watching, filesystem-monitoring, build-automation

[View on SkillFed](https://skillfed.io/packages/pywatchman) · [View on PyPI](https://pypi.org/project/pywatchman/)