Install & Compatibility
Where this runs
tested against v0.2.12 · 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
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.057s · 19.1MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 1.8s · import 0.060s · 20MB
17MB installed
● package 17MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Inotify
✓ from inotify.adapters import Inotify
✗ from inotify import Inotify
The primary class for interacting with inotify is located in the `adapters` submodule since version 0.2.x.
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)
Debug
Known issues
gotchaThis 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.fixEnsure your deployment environment is Linux. For cross-platform file system monitoring, consider libraries like `watchdog` which use OS-specific APIs under the hood.
affects: All versions
gotchaThe 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.fixIncrease 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.
affects: All versions
gotchaWatching 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.fixAvoid 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.
affects: All versions
breakingPrior 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+.fixIf 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.
affects: 0.1.x and earlier
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'inotify'
The Python interpreter cannot find the 'inotify' module. This often happens if the library is not installed, or if there's confusion with similarly named packages like 'pynotify', or if the installation is in a different Python environment than the one being used.
fixEnsure you have installed `pyinotify` (the correct package name for the Python wrapper to the Linux inotify API) in the active Python environment. If using a virtual environment, activate it before installing. `inotify` is also a separate, simpler wrapper, so confirm which one you intend to use. Most common case: `pip install pyinotify` or `pip install inotify` depending on the wrapper you intend to use.
AttributeError: 'Event' object has no attribute 'name'
This error occurs when attempting to access the `name` attribute of an `Event` object, but the specific event type does not inherently provide a `name` (e.g., if the event is on the watched directory itself, not an item within it), or if the `Event` object's structure is unexpected due to an older or corrupted installation.
fixThe `name` attribute should always be provided for relevant events (e.g., for `IN_CREATE`, `IN_DELETE`, etc.). Ensure your `pyinotify` installation is up to date. If `name` is `None` or an empty string, handle it gracefully by checking `if event.name:` before using it. For events that might not have a `name`, consider using `event.pathname` which is a concatenation of `path` and `name` or `event.path` directly.
InotifyError: Call failed (should not be -1): (-1) ERRNO=(0)
This generic `InotifyError` indicates that a low-level `inotify_init()` or `inotify_add_watch()` system call failed, returning -1. `ERRNO=(0)` suggests that the actual C `errno` was not propagated correctly, making the root cause harder to pinpoint, but it can often relate to kernel limits, permissions, or issues with the path being watched (e.g., path does not exist).
fixCommon causes include non-existent paths (verify the path exists and is accessible), reaching system limits for inotify watches or file descriptors (check `ulimit -n` and `/proc/sys/fs/inotify/max_user_watches`), or permission issues. Restarting the system has also been reported to resolve transient issues. If the error includes a specific `ERRNO`, consult Linux `errno` documentation (e.g., `EACCES` for permission denied, `EINVAL` for invalid arguments).
OSError: [Errno 24] Too many open files
The program has exceeded the maximum number of file descriptors it is allowed to have open simultaneously, which is a common issue when many directories or files are being watched by `inotify`.
fixIncrease the per-process file descriptor limit using `ulimit -n <new_limit>` in your shell (temporary) or by modifying `/etc/security/limits.conf` (permanent). Also, ensure your application properly removes watches (`rm_watch()`) and closes the `inotify` instance when no longer needed to release resources.
OSError: [Errno 13] Permission denied
The `inotify` instance or the process running it lacks the necessary read or execute permissions for the directory or file it is trying to watch.
fixEnsure the user running the Python script has appropriate read and execute permissions on the target directories and files. This may involve changing file permissions (`chmod`) or ownership (`chown`) or running the script with `sudo` if necessary, though `sudo` should be used cautiously.
Upgrade
Version history
0.2.12latest on PyPI · released Jul 7, 2025
Audit
Dependencies
No dependency data recorded yet.