Install & Compatibility
Where this runs
tested against v? · pip install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
build_error
glibcpy 3.10–3.920 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
client
✓ import pywatchman
client = pywatchman.client()
✗ from watchman_client import Client
The `watchman_client` import belongs to a different, unofficial client library (orf/watchman-client). The official pywatchman library uses `pywatchman.client()`.
bser
✓ from pywatchman import bser
Imports the BSER (Binary Serialization) module for efficient data exchange with the Watchman daemon.
This quickstart demonstrates how to connect to the Watchman daemon, establish a watch on a directory, and then query for recently changed Python files within that watched directory. It includes basic error handling for when the Watchman service is not available.
import pywatchman
import os
def main():
try:
# Establish a connection to the Watchman daemon
client = pywatchman.client()
print(f"Connected to Watchman: {client.query('get-sockname')['sockname']}")
# Define the directory to watch (current directory for example)
watch_dir = os.getcwd()
print(f"Attempting to watch directory: {watch_dir}")
# Tell Watchman to start watching the directory
# This will return existing watch if already present
watch_result = client.query('watch', watch_dir)
print(f"Watch established: {watch_result}")
# Perform a query for Python files that have changed since the last clock
# The 'clock' value is automatically managed by Watchman
query_result = client.query(
'query', watch_dir, {
'expression': ['allof', ['type', 'f'], ['suffix', 'py']],
'fields': ['name', 'size', 'mtime_ms']
}
)
print("\nRecently changed Python files:")
for f in query_result.get('files', []):
print(f" - {f['name']} (size: {f['size']} bytes, modified: {f['mtime_ms']}ms ago)")
except pywatchman.Unavailable as e:
print(f"Error: Watchman service is unavailable. Please ensure Watchman is installed and running. Details: {e}")
except Exception as e:
print(f"An unexpected error occurred: {e}")
if __name__ == '__main__':
main()
Debug
Known issues
gotchapywatchman is a client library and requires the separate Watchman daemon to be installed and running on your system. It is not a standalone file watcher written purely in Python.fixEnsure the Watchman daemon is installed and started according to the official Watchman documentation for your operating system (e.g., via Homebrew on macOS, package managers on Linux).
affects: All versions
breakingOlder versions of pywatchman (specifically 1.4.1) were known to raise a `SystemError` on Python 3.10+ due to issues with internal C extensions related to the `PY_SSIZE_T_CLEAN` macro.fixUpgrade pywatchman to a modern version (2.0.0 or 3.0.0+). These versions provide compatibility with newer Python releases (Python >=3.8 is currently required for 3.0.0).
affects: 1.x (especially 1.4.1) on Python 3.10 and newer
gotchaDedicated documentation for the pywatchman Python API is limited. Users often need to refer to the Watchman daemon's general command documentation and the pywatchman source code for detailed usage examples and API specifics.fixConsult the main Watchman documentation for command structures and parameters, and review the pywatchman GitHub repository's `pywatchman/__init__.py` for direct API exploration.
affects: All versions
gotchaIssues have been reported where `ignore_dirs` in the `.watchmanconfig` file are not always respected by `WatchmanReloader` integrations (e.g., in Django), leading to excessive file watching in ignored paths like virtual environments or system Python directories.fixVerify your `.watchmanconfig` syntax. If the issue persists, consider explicit subscription filters in your client code or investigate specific framework integration configurations. This might require debugging the interaction between the framework and pywatchman.
affects: Potentially all versions, especially with framework integrations like Django's WatchmanReloader
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'pywatchman'
The 'pywatchman' library is not installed in the current Python environment.
fixInstall the library using pip: `pip install pywatchman`.
pywatchman.client.WatchmanError: Failed to connect to Watchman
The Watchman daemon is not running, is inaccessible, or a general connection issue occurred preventing the 'pywatchman' client from establishing a link.
fixEnsure the Watchman daemon is running (e.g., `watchman --foreground` or as a service) and is accessible from the current user/environment.
FileNotFoundError: [Errno 2] No such file or directory: '/tmp/watchman-user/sock'
The Watchman daemon's socket file, which 'pywatchman' attempts to connect to, does not exist at the default or specified path, often indicating the daemon is not running or is misconfigured.
fixStart the Watchman daemon and verify that its socket file is created and accessible. If 'watchman' is configured for a non-default socket path, pass `sockpath` to `pywatchman.client.WatchmanClient`.
TypeError: the JSON query must be a list
The `query` method of `pywatchman.client.WatchmanClient` expects its `query_tuple` argument to be a list (or tuple) representing the Watchman command, but a scalar type (like a string) was provided.
fixWrap the Watchman command in a list: `client.query(['version'])` instead of `client.query('version')`. Upgrade
Version history
4.0.0latest on PyPI · released Jun 12, 2026
Audit
Dependencies
watchmanrequiredpywatchman is a client library; the Watchman daemon must be installed and running on the system for it to function.