{"id":6842,"library":"pywatchman","title":"pywatchman","description":"pywatchman is a Python client library for Facebook's Watchman file watching service. It provides a simple interface to connect to and query the Watchman daemon to efficiently discover file system changes. The library is actively maintained with frequent development tags on GitHub, and new PyPI releases (currently 3.0.0) are made periodically.","status":"active","version":"3.0.0","language":"en","source_language":"en","source_url":"https://github.com/facebook/watchman","tags":["file monitoring","watchman","filesystem events","daemon client"],"install":[{"cmd":"pip install pywatchman","lang":"bash","label":"Install pywatchman"}],"dependencies":[{"reason":"pywatchman is a client library; the Watchman daemon must be installed and running on the system for it to function.","package":"watchman","optional":false}],"imports":[{"note":"The `watchman_client` import belongs to a different, unofficial client library (orf/watchman-client). The official pywatchman library uses `pywatchman.client()`.","wrong":"from watchman_client import Client","symbol":"client","correct":"import pywatchman\nclient = pywatchman.client()"},{"note":"Imports the BSER (Binary Serialization) module for efficient data exchange with the Watchman daemon.","symbol":"bser","correct":"from pywatchman import bser"}],"quickstart":{"code":"import pywatchman\nimport os\n\ndef main():\n    try:\n        # Establish a connection to the Watchman daemon\n        client = pywatchman.client()\n        print(f\"Connected to Watchman: {client.query('get-sockname')['sockname']}\")\n\n        # Define the directory to watch (current directory for example)\n        watch_dir = os.getcwd()\n        print(f\"Attempting to watch directory: {watch_dir}\")\n\n        # Tell Watchman to start watching the directory\n        # This will return existing watch if already present\n        watch_result = client.query('watch', watch_dir)\n        print(f\"Watch established: {watch_result}\")\n\n        # Perform a query for Python files that have changed since the last clock\n        # The 'clock' value is automatically managed by Watchman\n        query_result = client.query(\n            'query', watch_dir, {\n                'expression': ['allof', ['type', 'f'], ['suffix', 'py']],\n                'fields': ['name', 'size', 'mtime_ms']\n            }\n        )\n        print(\"\\nRecently changed Python files:\")\n        for f in query_result.get('files', []):\n            print(f\" - {f['name']} (size: {f['size']} bytes, modified: {f['mtime_ms']}ms ago)\")\n\n    except pywatchman.Unavailable as e:\n        print(f\"Error: Watchman service is unavailable. Please ensure Watchman is installed and running. Details: {e}\")\n    except Exception as e:\n        print(f\"An unexpected error occurred: {e}\")\n\nif __name__ == '__main__':\n    main()","lang":"python","description":"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."},"warnings":[{"fix":"Ensure 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).","message":"pywatchman 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Upgrade 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).","message":"Older 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.","severity":"breaking","affected_versions":"1.x (especially 1.4.1) on Python 3.10 and newer"},{"fix":"Consult the main Watchman documentation for command structures and parameters, and review the pywatchman GitHub repository's `pywatchman/__init__.py` for direct API exploration.","message":"Dedicated 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Verify 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.","message":"Issues 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.","severity":"gotcha","affected_versions":"Potentially all versions, especially with framework integrations like Django's WatchmanReloader"}],"env_vars":null,"last_verified":"2026-04-15T00:00:00.000Z","next_check":"2026-07-14T00:00:00.000Z","problems":[]}