---
id: watchdog
version: "6.0.0"
license: Apache-2.0
license_treatment: permissive
maintenance: active
---

# watchdog — Filesystem events monitoring

License: permissive · Maintenance: active · Popularity: top 1,000 on PyPI

## Install

pip install watchdog
uv add watchdog
poetry add watchdog

## Description

Watchdog
========

|PyPI Version|
|PyPI Status|
|PyPI Python Versions|
|GitHub Build Status|
|GitHub License|

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

## AI interpretation — verify before relying

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.

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+.

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