{"id":6677,"library":"inotify","title":"PyInotify","description":"PyInotify is a Python adapter to the Linux kernel's inotify directory-watching interface. It provides a simple and efficient way to monitor filesystem events like file creation, deletion, modification, and access. The current version is 0.2.12, with releases typically occurring as needed for bug fixes or minor enhancements.","status":"active","version":"0.2.12","language":"en","source_language":"en","source_url":"https://github.com/dsoprea/PyInotify","tags":["filesystem","monitoring","linux","events"],"install":[{"cmd":"pip install inotify","lang":"bash","label":"Install with pip"}],"dependencies":[],"imports":[{"note":"The primary class for interacting with inotify is located in the `adapters` submodule since version 0.2.x.","wrong":"from inotify import Inotify","symbol":"Inotify","correct":"from inotify.adapters import Inotify"}],"quickstart":{"code":"import os\nimport time\nfrom inotify.adapters import Inotify\n\n# Create a temporary directory for demonstration\ntest_dir = \"./inotify_test_dir\"\nif not os.path.exists(test_dir):\n    os.makedirs(test_dir)\n\n# Initialize inotify adapter\ni = Inotify()\n\n# Add a watch for the directory and its subdirectories\n# mask=Inotify.ALL_EVENTS covers most common operations\ni.add_watch(test_dir, mask=Inotify.ALL_EVENTS)\n\nprint(f\"Watching directory: {test_dir} for all events...\")\nprint(\"Try creating, modifying, or deleting files/directories inside it.\")\nprint(\"Press Ctrl+C to stop.\")\n\ntry:\n    # event_gen yields (event_tuple) or None if yield_nones=True\n    # A tuple typically contains (wd, mask, cookie, name).\n    # The adapter enhances this to (header, type_names, path, filename)\n    for event in i.event_gen(yield_nones=False):\n        (_, type_names, path, filename) = event\n        print(f\"Event detected: TYPE={type_names}, PATH={path}, FILENAME={filename}\")\nexcept KeyboardInterrupt:\n    print(\"\\nStopping inotify watch.\")\nfinally:\n    # Always remove the watch when done\n    i.remove_watch(test_dir)\n    # Clean up the test directory\n    if os.path.exists(test_dir):\n        for root, dirs, files in os.walk(test_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(test_dir)","lang":"python","description":"This example demonstrates how to set up a watch on a directory and print detected filesystem events. It creates a temporary directory, adds a recursive watch for all event types, and then continuously listens for events. It handles graceful shutdown and cleans up the temporary directory."},"warnings":[{"fix":"Ensure your deployment environment is Linux. For cross-platform file system monitoring, consider libraries like `watchdog` which use OS-specific APIs under the hood.","message":"This library is an adapter to the Linux kernel's inotify interface and is therefore Linux-specific. It will not work on other operating systems like Windows or macOS.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Increase kernel parameters `fs.inotify.max_queued_events` or `fs.inotify.max_user_watches` (e.g., `sudo sysctl -w fs.inotify.max_queued_events=100000`). Design your event processing to be as fast as possible, potentially offloading heavy work to a separate thread or process.","message":"The inotify event queue has a finite size. If events are generated faster than they can be processed, the queue can overflow, leading to missed events. This is a kernel limitation, not specific to PyInotify.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Avoid watching sensitive or very active system directories unless absolutely necessary. Run your application with the minimum required permissions. Filter events as early as possible if monitoring broad paths.","message":"Watching certain system directories (e.g., `/proc`, `/sys`, or root `/`) may require elevated permissions (root) or specific capabilities, and can generate a very high volume of events, impacting performance.","severity":"gotcha","affected_versions":"All versions"},{"fix":"If migrating from 0.1.x, refactor your code to use the `inotify.adapters.Inotify` class and its methods (`add_watch`, `event_gen`, `remove_watch`). Consult the latest README for current usage patterns.","message":"Prior to version 0.2.x, the library's API was lower-level and involved directly interacting with `inotify.watcher`. Version 0.2.x introduced the `inotify.adapters` module, which provides a higher-level, more user-friendly interface. Code written for 0.1.x will not be directly compatible with 0.2.x+.","severity":"breaking","affected_versions":"0.1.x and earlier"}],"env_vars":null,"last_verified":"2026-04-15T00:00:00.000Z","next_check":"2026-07-14T00:00:00.000Z","problems":[]}