PyInotify

Warnings

• gotcha 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.
  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.
• gotcha 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.
  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.
• gotcha 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.
  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.
• breaking 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+.
  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.

Install

• pip install inotify Install with pip

Imports

• Inotify
  wrong:

  from inotify import Inotify

  correct:

  from inotify.adapters import Inotify

  The primary class for interacting with inotify is located in the `adapters` submodule since version 0.2.x.

Quickstart

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.

import os
import time
from inotify.adapters import Inotify

# Create a temporary directory for demonstration
test_dir = "./inotify_test_dir"
if not os.path.exists(test_dir):
    os.makedirs(test_dir)

# Initialize inotify adapter
i = Inotify()

# Add a watch for the directory and its subdirectories
# mask=Inotify.ALL_EVENTS covers most common operations
i.add_watch(test_dir, mask=Inotify.ALL_EVENTS)

print(f"Watching directory: {test_dir} for all events...")
print("Try creating, modifying, or deleting files/directories inside it.")
print("Press Ctrl+C to stop.")

try:
    # event_gen yields (event_tuple) or None if yield_nones=True
    # A tuple typically contains (wd, mask, cookie, name).
    # The adapter enhances this to (header, type_names, path, filename)
    for event in i.event_gen(yield_nones=False):
        (_, type_names, path, filename) = event
        print(f"Event detected: TYPE={type_names}, PATH={path}, FILENAME={filename}")
except KeyboardInterrupt:
    print("\nStopping inotify watch.")
finally:
    # Always remove the watch when done
    i.remove_watch(test_dir)
    # Clean up the test directory
    if os.path.exists(test_dir):
        for root, dirs, files in os.walk(test_dir, topdown=False):
            for name in files:
                os.remove(os.path.join(root, name))
            for name in dirs:
                os.rmdir(os.path.join(root, name))
        os.rmdir(test_dir)