---
id: inotify
version: "0.2.12"
license: GPL 2
license_treatment: copyleft
maintenance: aging
---

# inotify — An adapter to Linux kernel support for inotify directory-watching.

License: copyleft · Maintenance: aging · Downloads: 393.1K/mo

## What it is and what it does

inotify is a Python adapter to the Linux kernel's inotify subsystem, which lets you register directories and receive notifications when files or subdirectories change, create, or delete. Instead of polling directories repeatedly, your code blocks and waits for kernel events, making it far more efficient for file-watching tasks. The library presents events as a generator—you loop through them one at a time, with optional timeouts between cycles, and can optionally receive None values to perform other work between event batches.

The package supports both flat directory watching (via Inotify) and recursive tree watching (via InotifyTree), which automatically manages watches on child directories as they are created. It uses epoll internally to audit kernel events and has been designed to handle Python 3 string/bytes conversions transparently. The library is Linux-only and requires kernel version 2.6 or later.

Use it for:

- Monitor a directory for file uploads or changes and trigger processing pipelines when new files arrive.
- Watch a configuration directory and reload application settings when files are modified.
- Implement a recursive directory watcher to track all file system events in a project tree for backup or sync tools.
- Build a file-system-driven event loop where inotify events drive application logic rather than a timer.
- Detect when log files are rotated or new logs appear and react without polling.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Wraps Linux kernel inotify to watch directories for file system events, yielding them as a generator rather than requiring polling.

Yes, if your application runs on Linux and needs efficient file-system event monitoring. The low install friction, lack of known vulnerabilities, and straightforward generator-based API make it a solid choice for the task. The GPL 2 copyleft license is a hard blocker for proprietary software; open-source projects under compatible licenses should evaluate the aging maintenance status (403 days since last release) and confirm Python version compatibility before committing.

## Install

pip install inotify
uv add inotify
poetry add inotify

## Installing inotify

Before you install: Low friction pure-Python wheel. Maintenance status is aging—last release was 403 days ago—but the repository remains active and unarchived with modest community interest (261 stars).

License in practice: GPL 2 copyleft license. Any application that links this library must be distributed under GPL 2 or a compatible copyleft license; proprietary or permissively-licensed projects cannot use it without legal review.

Quickstart:

import inotify.adapters

i = inotify.adapters.Inotify()
i.add_watch('/tmp')

for event in i.event_gen(yield_nones=False):
    (_, type_names, path, filename) = event
    print(f"PATH=[{path}] FILENAME=[{filename}] EVENT_TYPES={type_names}")

Linux kernel only; inotify is not available on macOS, Windows, or other non-Linux systems.

Verify before relying:

- Whether the aging maintenance status (403 days since last release) indicates active stewardship or dormancy risk.
- Python version compatibility—requires_python is unspecified; unclear which Python versions are actually supported.

## Package facts

- License: GPL 2 (copyleft)
- Python support: unspecified
- Install friction: low
- Maintenance: aging
- Downloads: 393.1K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

linux file system monitoring, inotify directory watching, file change detection, kernel event notifications, directory event generator, filesystem watcher, linux file events, linux-only, file-watching, copyleft

[View on SkillFed](https://skillfed.io/packages/inotify) · [View on PyPI](https://pypi.org/project/inotify/)