{"id":2219,"library":"pyinotify","title":"pyinotify","description":"pyinotify is a Python library that provides a straightforward interface to the Linux kernel's inotify subsystem. It allows applications to monitor filesystem events like file creation, deletion, modification, and access in a given directory or hierarchy. The current version is 0.9.6, released in 2015. The project has since been in a maintenance mode with occasional updates to ensure Python compatibility, rather than active feature development.","status":"maintenance","version":"0.9.6","language":"en","source_language":"en","source_url":"https://github.com/seb-m/pyinotify","tags":["filesystem","monitoring","linux","inotify"],"install":[{"cmd":"pip install pyinotify","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"symbol":"WatchManager","correct":"import pyinotify\nwm = pyinotify.WatchManager()"},{"symbol":"Notifier","correct":"import pyinotify\nnotifier = pyinotify.Notifier(wm, event_handler)"},{"symbol":"ProcessEvent","correct":"import pyinotify\nclass MyHandler(pyinotify.ProcessEvent): ..."}],"quickstart":{"code":"import pyinotify\nimport os\nimport time\n\n# Create a temporary directory for demonstration\nwatch_dir = \"/tmp/pyinotify_example_dir\"\nos.makedirs(watch_dir, exist_ok=True)\nprint(f\"Watching directory: {watch_dir}\")\nprint(\"Try 'touch {watch_dir}/file1' or 'rm {watch_dir}/file1'\")\nprint(\"Press Ctrl+C to stop.\")\n\nclass EventHandler(pyinotify.ProcessEvent):\n    def process_IN_CREATE(self, event):\n        print(f\"Created: {event.pathname}\")\n\n    def process_IN_DELETE(self, event):\n        print(f\"Deleted: {event.pathname}\")\n\nwm = pyinotify.WatchManager()\nmask = pyinotify.IN_CREATE | pyinotify.IN_DELETE\n\n# Attach the WatchManager and EventHandler to a Notifier\nnotifier = pyinotify.Notifier(wm, EventHandler())\n\n# Add a watch to the directory for the specified events\n# rec=True ensures subdirectories are also watched\nwm.add_watch(watch_dir, mask, rec=True)\n\ntry:\n    # Start processing events. This method blocks indefinitely.\n    # For non-blocking, use notifier.process_events() in a custom loop.\n    notifier.loop()\nexcept KeyboardInterrupt:\n    print(\"\\nStopping watcher.\")\nfinally:\n    notifier.stop() # Clean up inotify resources\n    # Clean up the example directory\n    if os.path.exists(watch_dir):\n        # Ensure directory is empty before removing\n        for root, dirs, files in os.walk(watch_dir, topdown=False):\n            for name in files:\n                os.remove(os.path.join(root, name))\n            for name in dirs:\n                os.rmdir(os.path.join(root, name))\n        os.rmdir(watch_dir)\n","lang":"python","description":"This quickstart demonstrates how to set up a basic `pyinotify` watcher to monitor a directory for file creation and deletion events. It creates a temporary directory, sets up an `EventHandler` to print messages, and then uses `notifier.loop()` to block and process events. Remember to press Ctrl+C to stop the blocking loop. The `finally` block ensures proper cleanup of the inotify resources and the temporary directory."},"warnings":[{"fix":"Ensure your application is deployed on a Linux environment. For cross-platform filesystem monitoring, consider libraries like `watchdog` which use different backend mechanisms.","message":"`pyinotify` is inherently Linux-specific, as it directly interfaces with the `inotify` kernel subsystem. It will not work on other operating systems like macOS or Windows, and attempting to use it will result in errors.","severity":"breaking","affected_versions":"All versions"},{"fix":"For non-blocking operations, implement a custom loop using `notifier.process_events(timeout=...)` or run the `notifier.loop()` in a dedicated thread.","message":"The `notifier.loop()` method is blocking and will prevent the rest of your application from executing. If you need non-blocking behavior (e.g., in a GUI application or when integrating with `asyncio`), you must use `notifier.process_events()` with a timeout within your own event loop or a separate thread.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Process events promptly. Consider increasing the kernel's inotify queue size (`/proc/sys/fs/inotify/max_queued_events`) if you expect very high event volumes, but be aware of memory implications. Ensure your event handlers are efficient.","message":"If events are generated faster than they can be processed, the kernel's inotify event queue can overflow, leading to missed events. The default queue size is usually limited (e.g., 16384 events).","severity":"gotcha","affected_versions":"All versions"},{"fix":"Carefully review the `pyinotify` documentation for `add_watch` flags. `rec=True` monitors existing subdirectories. `auto_add=True` will automatically add watches for *newly created* subdirectories, which is often desired for comprehensive recursive monitoring.","message":"Misunderstanding `wm.add_watch()` flags like `rec=True` (recursive) and `auto_add=True` can lead to unintended behavior, such as watching too many files/directories, or missing events for newly created directories that weren't explicitly watched.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}