Registry / devops / inotify-simple

inotify-simple

JSON →
library2.0.1pypypi✓ verified 22d ago

inotify-simple is a lightweight Python wrapper around the Linux `inotify` API, implemented using `ctypes`. It provides a direct, low-level interface to filesystem events without much abstraction, making it efficient and close to the kernel's behavior. The library is currently at version 2.0.1 and is actively maintained with a stable release cadence.

pip install inotify-simple
INSTALL
IMPORT
SIG · INOTIFY-SIMPLE
I
inotify-simple
devopspythonv2.0.1
Install
1.5s avg
Import
40ms
Disk
16MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v2.0.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.95 runs
installs and imports cleanly · install 0.0s · import 0.038s · 17.8MB
glibc
py 3.103.95 runs
installs and imports cleanly · install 1.5s · import 0.042s · 18MB
16MB installed
● package 16MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

INotify
from inotify_simple import INotify
Main class for interacting with the inotify file descriptor.
flags
from inotify_simple import flags
Enum containing inotify event flags (e.g., CREATE, MODIFY, DELETE).
Event
from inotify_simple import Event
Namedtuple returned by INotify.read() representing a filesystem event.

This example demonstrates how to set up a basic `inotify` watch on a directory for creation, deletion, modification, and close-write events. It then continuously reads and prints detected events. It also shows how to gracefully stop the monitoring and clean up resources.

import os import time from inotify_simple import INotify, flags # Create a temporary directory to watch watch_dir = '/tmp/inotify_test_simple' os.makedirs(watch_dir, exist_ok=True) inotify = INotify() # Add a watch for create, delete, and modify events # flags.CLOSE_WRITE is often useful for 'file saved' events watch_flags = flags.CREATE | flags.DELETE | flags.MODIFY | flags.CLOSE_WRITE wd = inotify.add_watch(watch_dir, watch_flags) print(f"Watching directory: {watch_dir} (watch descriptor: {wd})") print("Create, modify, or delete files in this directory. Press Ctrl+C to exit.") try: while True: # Read events with a timeout (e.g., 1000 ms = 1 second) # Events are returned as a list of namedtuple objects events = inotify.read(timeout=1000) if not events: # print("No events in the last second.") # Uncomment for verbose output continue for event in events: print(f"Event: wd={event.wd}, mask={event.mask} ({flags.from_mask(event.mask)}), cookie={event.cookie}, name='{event.name}'") # Example: react to a file creation if flags.CREATE in flags.from_mask(event.mask): print(f" New file/directory created: {os.path.join(watch_dir, event.name)}") if flags.DELETE in flags.from_mask(event.mask): print(f" File/directory deleted: {os.path.join(watch_dir, event.name)}") if flags.CLOSE_WRITE in flags.from_mask(event.mask): print(f" File written and closed: {os.path.join(watch_dir, event.name)}") except KeyboardInterrupt: print("Monitoring stopped.") finally: inotify.rm_watch(wd) inotify.close() # Clean up the temporary directory # os.rmdir(watch_dir) # Only if empty print(f"Removed watch for {watch_dir} and closed inotify instance.")
Debug
Known issues
gotchainotify, and by extension `inotify-simple`, does not recursively monitor subdirectories. To monitor an entire directory tree, you must explicitly add watches for each subdirectory. New subdirectories created after the initial setup will also require new watches to be added programmatically.
fix
Implement logic to recursively add watches for new and existing subdirectories. Continuously scan for new directories if full recursive monitoring is required.
affects: All versions
gotchaThe `INotify.read()` method is blocking by default when `timeout` is `None` or negative. If your application needs to perform other tasks while waiting for events, use a non-blocking approach (e.g., `timeout=0` or a positive timeout) or integrate with `select.select()`/`selectors` to monitor multiple file descriptors, including the `inotify` instance.
fix
Set a `timeout` argument in `INotify.read()` or wrap the `INotify` instance with `select.select()` or an `asyncio` event loop to handle concurrent I/O operations.
affects: All versions
gotchaThe kernel's `inotify` event queue has a limited size (`/proc/sys/fs/inotify/max_queued_events`). If events are generated faster than they are consumed by the application, the queue can overflow, leading to lost events. Robust applications should anticipate and handle this possibility.
fix
Increase kernel limits (`sysctl -w fs.inotify.max_queued_events=...`). Design event processing to be as fast as possible to minimize queue backlog, or implement a recovery strategy (e.g., rescan monitored directories) if an overflow event (`flags.Q_OVERFLOW`) is received.
affects: All versions
gotcha`inotify` events are reported with a watch descriptor (`wd`) and a `name` (filename). The `name` field might refer to a file that has already been deleted or renamed by the time the event is processed. It is the application's responsibility to maintain a mapping between `wd`s and current file paths if needed, and to handle stale `name` references.
fix
Maintain a dictionary mapping watch descriptors (`wd`) to full paths. When processing events, use the `wd` to retrieve the most current path from your cache, and be prepared for the `name` field to be outdated or point to a non-existent file.
affects: All versions
gotchaThe `inotify` API does not provide information about the user or process that triggered a filesystem event. All events appear to originate from the kernel. Also, it does not monitor events on network filesystems.
fix
If user/process attribution or network filesystem monitoring is required, `inotify-simple` is not the right tool. Consider auditing solutions or higher-level network file system APIs.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'inotify' OR ImportError: No module named 'inotify.adapters'
Developers often confuse 'inotify-simple' with other Python inotify wrappers (like 'python-inotify' or 'pyinotify') or incorrectly assume a submodule structure that does not exist in 'inotify-simple'.
fix
Ensure 'inotify-simple' is installed (`pip install inotify-simple`) and use the correct import statement for the library's main components, typically `from inotify_simple import INotify, flags`.
OSError: [Errno 28] No space left on device OR OSError: [Errno 24] Too many open files / inotify instance limit reached
These errors indicate that the system's kernel limits for the number of inotify watches or instances have been exhausted, which commonly occurs when monitoring a very large number of files or directories.
fix
Increase the kernel parameters `fs.inotify.max_user_watches`, `fs.inotify.max_user_instances`, and `fs.inotify.max_queued_events` by modifying `/etc/sysctl.conf` and reloading with `sudo sysctl -p`.
OSError: [Errno 2] No such file or directory
This error arises when `inotify.add_watch()` is called with a `path` that does not exist on the filesystem at the moment of the call, or when a directory is deleted while being monitored, and the watcher attempts to re-establish a watch on the now non-existent path.
fix
Verify that the `path` exists before attempting to add a watch. For dynamic scenarios involving deletions, catch the `OSError` and handle it gracefully, or consider watching the parent directory for creation events instead of specific files.
RuntimeError: can not find library c
The `inotify-simple` library uses Python's `ctypes` module to interface directly with the underlying Linux C standard library (`libc.so`). This error means `ctypes.util.find_library('c')` failed to locate this critical system library.
fix
Ensure that the standard C library (typically `libc.so.6` or similar) is correctly installed and discoverable on your Linux system. On Debian/Ubuntu-based systems, installing `libc6-dev` often resolves this issue.
Upgrade
Version history
2.0.1latest on PyPI · released Aug 25, 2025
Audit
Dependencies
pythonrequiredRequires Python 3.6 or higher for execution.
Agent activity
7 hits · last 30 days
node
6
Resources