watchdog

Filesystem events monitoring

watchdog Permissive license Apache-2.0 Active ★ 7,396 v6.0.0 released 2024-11-01

Install

watchdog on PyPI

pip

pip install watchdog

uv

uv add watchdog

poetry

poetry add watchdog

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 — 650 days since the last release
Last repo commit	2026-08-13
First released	2011-01-20
Popularity	one of the top 1,000 most-downloaded packages on PyPI (30-day window, as of 2026-08-13)
Known vulnerabilities	none known (OSV.dev, checked 2026-08-13)

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

Keywords: python, filesystem, monitoring, monitor, FSEvents, kqueue, inotify, ReadDirectoryChangesW, polling, DirectorySnapshot

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

About watchdog

from the package's own PyPI description — quoted content, verbatim

Watchdog

Python API and shell utilities to monitor file system events.

Works on 3.9+.

Example API Usage

A simple program that uses watchdog to monitor directories specified as command-line arguments and logs events generated:

.. code-block:: python

import time

from watchdog.events import FileSystemEvent, FileSystemEventHandler
from watchdog.observers import Observer


class MyEventHandler(FileSystemEventHandler):
    def on_any_event(self, event: FileSystemEvent) -&gt; None:
        print(event)


event_handler = MyEventHandler()
observer = Observer()
observer.schedule(event_handler, ".", recursive=True)
observer.start()
try:
    while True:
        time.sleep(1)
finally:
    observer.stop()
    observer.join()

Shell Utilities

Watchdog comes with an optional utility script called watchmedo. Please type watchmedo --help at the shell prompt to know more about this tool.

Here is how you can log the current directory recursively for events related only to *.py and...

Read as markdown · JSON record · Source repository · Homepage · Docs

AI interpretation — verify before relying

AI-generated interpretation of the package facts above; every digit, version, license, or vulnerability id it cites is grounded in the facts already shown on this page

Watchdog monitors file system events across Linux, macOS, Windows, and BSD, providing a Python API and command-line utilities to detect and react to file and directory changes in real time.

Medium install friction: watchdog ships platform-specific compiled wheels for macOS (multiple architectures and Python versions 3.9–3.13) and manylinux2014 aarch64, but lacks wheels for Windows and other Linux variants, requiring compilation on those platforms. Maintenance is active with recent releases and strong community engagement (7396 GitHub stars).

Watchdog is licensed under Apache License 2.0, a permissive license that allows commercial and private use with minimal restrictions, requiring only attribution and a copy of the license.

Usage

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()

Requires Python 3.9 or above. On macOS with kqueue, file descriptor limits may need adjustment (ulimit -n) for monitoring large directory trees. On some platforms, compiled extensions require build tools.

Verdict: Watchdog is a mature, actively maintained library (production/stable status, 7396 stars) with zero known vulnerabilities and permissive Apache 2.0 licensing. Medium install friction stems from platform-specific wheels; Windows and some Linux users will need compilation. Recommended for cross-platform file system monitoring in Python 3.9+.

Needs verification

Whether pre-built wheels are available for Windows and all common Linux distributions, or if compilation is required on those platforms
Performance characteristics and scalability limits when monitoring deeply nested directories or large file counts

file system event monitoringwatch directory for changesfilesystem observer pythondetect file modificationsinotify kqueue fsevents wrapperreal-time file system monitoringdirectory change detection