Registry / http-networking / asyncinotify

asyncinotify

JSON →
library4.4.4pypypi✓ verified 85d ago

asyncinotify is a simple, optionally-async Python inotify library, focusing on ease of use and modern Python features. It provides a Pythonic interface to Linux's inotify API, built on `ctypes` without external dependencies. The library is actively maintained, currently at version 4.4.4, and supports Python 3.6 and newer. It offers both asynchronous (async/await) and synchronous modes of operation for file system event monitoring.

pip install asyncinotify
INSTALL
IMPORT
SIG · ASYNCINOTIFY
A
asyncinotify
http-networkingpythonv4.4.4
Install
1.5s avg
Import
235ms
Disk
16MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v4.4.4 · 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.920 runs
installs and imports cleanly · install 0.0s · import 0.246s · 17.9MB
glibc
py 3.103.920 runs
installs and imports cleanly · install 1.5s · import 0.224s · 18MB
16MB installed
● package 16MB
Code
Verified usage

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

Inotify
from asyncinotify import Inotify
Mask
from asyncinotify import Mask

This quickstart demonstrates how to asynchronously watch a temporary directory for common file system events (create, modify, access, delete). It uses `Inotify` as a context manager to ensure the inotify handle is properly closed. Events are iterated asynchronously, printing details as they occur.

import asyncio import os import tempfile from pathlib import Path from asyncinotify import Inotify, Mask async def main(): # Create a temporary directory for watching with tempfile.TemporaryDirectory() as tmpdir_name: watch_path = Path(tmpdir_name) print(f"Watching directory: {watch_path}") with Inotify() as inotify: # Add a watch for various events inotify.add_watch( watch_path, Mask.ACCESS | Mask.MODIFY | Mask.OPEN | Mask.CREATE | Mask.DELETE | Mask.ATTRIB | Mask.CLOSE | Mask.MOVE | Mask.ONLYDIR ) print("Watch added. Creating a file in the directory...") # Create a file to trigger events test_file = watch_path / "test_file.txt" test_file.write_text("hello") await asyncio.sleep(0.1) # Give a moment for events to register test_file.unlink() await asyncio.sleep(0.1) # Give a moment for events to register print("File operations completed. Collecting events...") # Collect a few events. In a real application, you'd process them in a loop. events_collected = 0 async for event in inotify: print(f"Event: {event}") events_collected += 1 # Break after a few events or based on application logic if events_collected >= 3: # Adjust based on expected events break print("Finished collecting events.") asyncio.run(main())
Debug
Known issues
gotchaWhen a watched directory or file is moved, the `Event.path` property associated with subsequent events for that watch may become incorrect. The library does not automatically update the watch path. To correctly track moved paths, users must monitor the parent directory for `Mask.MOVE_SELF` events and re-add/update watches as needed.
fix
Implement logic to watch parent directories for `Mask.MOVE_SELF` or `Mask.MOVED_FROM`/`Mask.MOVED_TO` events, and programmatically update or re-add watches with the new paths.
affects: All versions
gotchaThe `Inotify` instance, when iterated asynchronously (`async for event in inotify:`), will yield events indefinitely (or until the inotify handle is closed). This is expected for continuous monitoring, but users must include their own logic (e.g., a `break` condition or `asyncio.wait_for`) to stop the iteration if only a finite number of events are expected or if the application needs to terminate.
fix
Ensure that asynchronous iteration loops have a defined exit condition, such as a counter, a timeout, or a signal-based shutdown mechanism.
affects: All versions
deprecatedThe library currently supports Python 3.6 and newer. However, the maintainers have stated that in a future version, Python support may be restricted to non-End-of-Life (EOL) versions if supporting older versions becomes inconvenient. Users should consider upgrading to actively supported Python versions to ensure future compatibility.
fix
Plan to migrate to Python versions that are actively supported by the Python community (e.g., Python 3.10+) to ensure continued compatibility and receive security updates.
affects: Future versions (post 4.x)
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'asyncinotify'
The 'asyncinotify' package is not installed in the Python environment.
fix
Install the package using pip: 'pip install asyncinotify'.
ImportError: cannot import name 'AsyncInotify' from 'asyncinotify'
The module 'asyncinotify' does not contain a class or function named 'AsyncInotify'.
fix
Ensure you are importing the correct class or function from 'asyncinotify'. Refer to the official documentation for the correct import statements.
AttributeError: module 'asyncinotify' has no attribute 'Inotify'
The 'Inotify' class is not present in the 'asyncinotify' module, possibly due to a version mismatch or incorrect installation.
fix
Verify that you have installed the correct version of 'asyncinotify' that includes the 'Inotify' class. Check the module's documentation for the correct usage.
OSError: [Errno 2] No such file or directory
This error typically occurs when the path provided to `Inotify.add_watch()` does not exist on the filesystem.
fix
Ensure that the directory or file you are trying to watch with `inotify.add_watch()` exists before creating the watch.
UserWarning: inotify is a Linux-only API. You can package this library on other platforms, but not run it.
The `asyncinotify` library, by default, uses Linux's `inotify` API, which is not available on other operating systems like macOS or Windows. While recent FreeBSD versions (15+) also support inotify, this warning indicates an attempt to run the library on an unsupported platform.
fix
Run your application on a Linux-based operating system. If using FreeBSD 15+, the warning might still appear but the functionality should be available.
Upgrade
Version history
4.4.4latest on PyPI · released Apr 13, 2026
Audit
Dependencies

No dependency data recorded yet.

Agent activity
24 hits · last 30 days
node
20
OpenAI (training)
1
Resources
asyncinotify — pip install asyncinotify · libregistry