watchdog
Filesystem events monitoring
Decision gist · record as of 2026-08-14
Yes. Watchdog is a mature, actively maintained library with no security vulnerabilities, permissive licensing, and zero runtime dependencies. It solves a genuine cross-platform problem with a clean API and is widely used (top 1000 on PyPI). Install it if you need to monitor file system events; the medium install friction is a one-time cost for reliable, platform-native behavior.AI-flagged interpretation of the facts on this page — verify before relying
Before you install
- Requires Python 3.9 or above.
- On kqueue systems (macOS, BSD), file descriptor limits may need adjustment via ulimit if monitoring many files.
- Medium install friction due to compiled wheels for multiple Python versions and platforms, but the package is actively maintained with a recent commit on 2026-08-13 and no runtime dependencies to manage.
License · maintenance · safety
Apache-2.0 (permissive) — Licensed under Apache License, version 2.0 (permissive), allowing use in commercial and private projects with minimal restrictions beyond attribution.
last release 2024-11-01 (651 days) · last repo commit 2026-08-13 · 7,396 stars
0 known vulnerabilities (OSV.dev, 2026-08-14) · 112,147,750 downloads/mo, #318 on PyPI
Alternatives
Verify before relying
from watchdog.events import FileSystemEventHandler
from watchdog.observers import Observer
import time
class MyEventHandler(FileSystemEventHandler):
def on_any_event(self, event):
print(event)
observer = Observer()
observer.schedule(MyEventHandler(), ".", recursive=True)
observer.start()
try:
while True:
time.sleep(1)
finally:
observer.stop()
observer.join()- Performance characteristics when monitoring deeply nested directories with thousands of files on different platforms.
- Behavior and event accuracy when watchdog is used with network file systems beyond CIFS.
What it is and what it does
Watchdog is a cross-platform file system event monitoring library that abstracts platform-specific mechanisms—inotify on Linux, FSEvents and kqueue on macOS and BSD, ReadDirectoryChangesW on Windows, and polling fallback—into a unified Python API. It lets you write event handlers that respond to file creation, modification, deletion, and directory changes as they happen, rather than polling the disk yourself.
The package includes both a programmatic API (via Observer and FileSystemEventHandler classes) and a command-line utility called watchmedo for scripting file system reactions. It supports pattern matching to filter events, recursive directory monitoring, and a plugin system for custom event handlers. With no runtime dependencies and support for Python 3.9 and above, it integrates directly into applications that need to react to file system changes—from development tools to automation scripts.
Use it for
- Auto-reload development servers when source files change during local development.
- Trigger build or test pipelines in response to file modifications in a watched directory.
- Monitor log files or data directories and execute shell commands or custom logic when new files appear.
- Implement file synchronization or backup tools that react to changes in real time.
- Build IDE-like features that detect when external tools modify project files on disk.
Worth the install?
AI-flagged interpretation of the facts on this page. Verify before relying on it.
Yes.
Watchdog is a mature, actively maintained library with no security vulnerabilities, permissive licensing, and zero runtime dependencies. It solves a genuine cross-platform problem with a clean API and is widely used (top 1000 on PyPI). Install it if you need to monitor file system events; the medium install friction is a one-time cost for reliable, platform-native behavior.
Install
watchdog on PyPI
Before you install
Medium install friction due to compiled wheels for multiple Python versions and platforms, but the package is actively maintained with a recent commit on 2026-08-13 and no runtime dependencies to manage.
Requires Python 3.9 or above. On kqueue systems (macOS, BSD), file descriptor limits may need adjustment via ulimit if monitoring many files.
License in practice
Licensed under Apache License, version 2.0 (permissive), allowing use in commercial and private projects with minimal restrictions beyond attribution.
Quickstart
from watchdog.events import FileSystemEventHandler
from watchdog.observers import Observer
import time
class MyEventHandler(FileSystemEventHandler):
def on_any_event(self, event):
print(event)
observer = Observer()
observer.schedule(MyEventHandler(), ".", recursive=True)
observer.start()
try:
while True:
time.sleep(1)
finally:
observer.stop()
observer.join()Verify before relying
- Performance characteristics when monitoring deeply nested directories with thousands of files on different platforms.
- Behavior and event accuracy when watchdog is used with network file systems beyond CIFS.
Package facts
| License | Apache-2.0 permissive |
| Python support | Supports the current Python release >=3.9 |
| Install friction | Medium. Platform-specific wheel |
| Runtime dependencies | None |
| Maintenance | Actively maintained 651 days since the last release |
| Last repo commit | |
| First released | |
| Downloads | 112,147,750 / month, #318 on PyPI 30-day window, as of 2026-08-14 |
| Known vulnerabilities | None known OSV.dev, checked 2026-08-14 |
| Classifiers | Development Status :: 5 - Production/StableEnvironment :: ConsoleIntended Audience :: DevelopersIntended Audience :: System AdministratorsLicense :: OSI Approved :: Apache Software LicenseNatural Language :: EnglishOperating System :: MacOS :: MacOS XOperating System :: Microsoft :: Windows :: Windows 10Operating System :: Microsoft :: Windows :: Windows 11Operating System :: Microsoft :: Windows :: Windows 7Operating System :: Microsoft :: Windows :: Windows 8Operating System :: Microsoft :: Windows :: Windows 8.1Operating System :: Microsoft :: Windows :: Windows VistaOperating System :: OS IndependentOperating System :: POSIX :: BSDOperating System :: POSIX :: LinuxProgramming Language :: CProgramming Language :: PythonProgramming Language :: Python :: 3Programming Language :: Python :: 3 :: OnlyProgramming Language :: Python :: 3.10Programming Language :: Python :: 3.11Programming Language :: Python :: 3.12Programming Language :: Python :: 3.13Programming Language :: Python :: 3.9Programming Language :: Python :: Implementation :: CPythonProgramming Language :: Python :: Implementation :: PyPyTopic :: Software Development :: LibrariesTopic :: System :: FilesystemsTopic :: System :: MonitoringTopic :: Utilities |
Evidence: watchdog-6.0.0-cp310-cp310-macosx_10_9_universal2.whl; watchdog-6.0.0-cp310-cp310-macosx_10_9_x86_64.whl; watchdog-6.0.0-cp310-cp310-macosx_11_0_arm64.whl; watchdog-6.0.0-cp311-cp311-macosx_10_9_universal2.whl; watchdog-6.0.0-cp311-cp311-macosx_10_9_x86_64.whl; watchdog-6.0.0-cp311-cp311-macosx_11_0_arm64.whl; watchdog-6.0.0-cp312-cp312-macosx_10_13_universal2.whl; watchdog-6.0.0-cp312-cp312-macosx_10_13_x86_64.whl; watchdog-6.0.0-cp312-cp312-macosx_11_0_arm64.whl; watchdog-6.0.0-cp313-cp313-macosx_10_13_universal2.whl; watchdog-6.0.0-cp313-cp313-macosx_10_13_x86_64.whl; watchdog-6.0.0-cp313-cp313-macosx_11_0_arm64.whl; watchdog-6.0.0-cp39-cp39-macosx_10_9_universal2.whl; watchdog-6.0.0-cp39-cp39-macosx_10_9_x86_64.whl; watchdog-6.0.0-cp39-cp39-macosx_11_0_arm64.whl; watchdog-6.0.0-pp310-pypy310_pp73-macosx_10_15_x86_64.whl; watchdog-6.0.0-pp310-pypy310_pp73-macosx_11_0_arm64.whl; watchdog-6.0.0-pp39-pypy39_pp73-macosx_10_15_x86_64.whl; watchdog-6.0.0-pp39-pypy39_pp73-macosx_11_0_arm64.whl; watchdog-6.0.0-py3-none-manylinux2014_aarch64.whl
Tags
Let your AI agent find packages like this
Example. Real query, live index.
You found this page by searching. An agent finds it by wishing: SkillFed indexes 14,416 PyPI packages by what they can do, searchable in plain language.
wish › “inotify kqueue fsevents”
- watchdogWatchdog monitors file system events across Linux, macOS, Windows,…
- pywatchmanpywatchman is a Python client for Watchman, a file watching service…
- pyobjc-framework-FSEventsProvides Python bindings to macOS's FSEvents framework, allowing you…
Give your agent the search over MCP, or paste the wish link into any chat.
More Libraries packages
urllib3 is an HTTP client library that provides thread-safe connection pooling, SSL/TLS verification, multipart file uploads, request retries, compression support, and proxy handling for Python applications.
Requests is a Python HTTP library that simplifies sending HTTP/1.1 requests with automatic handling of headers, authentication, cookies, and response parsing.
Pluggy provides a plugin system that lets you define hook specifications and register implementations to be called in sequence, enabling extensible Python applications without tight coupling.
Install it if you're building an extensible application or framework.
Provides parsing, arithmetic, and recurrence rule computation for dates and times, with timezone support and iCalendar RFC compliance.
Install it if you need to parse flexible date strings, compute relative dates, handle timezones, or work with recurrence rules—it's the de facto choice for these tasks.
Six provides utility functions to write Python code that runs on both Python 2.7 and Python 3.3+, smoothing over language differences between the two versions.
pytest is a testing framework that lets you write test functions using plain assert statements and automatically discovers and runs them, with detailed failure reporting.
See also watchdog-gevent · pywatchman · pyinotify · pyobjc-framework-FSEvents · asyncinotify · inotify-simple · inotify · sdnotify · watchgod · fs