Watchdog

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

.. tip::

Become **my boss** to help me work on this awesome software, and make the world better:

|Patreon|

Python API and shell utilities to monitor file system events.

Browse the documentation_ online.

Works on 3.11+.

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 sys
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()
paths = sys.argv[1:] if len(sys.argv) > 1 else ["."]
for path in paths:
    observer.schedule(event_handler, path, recursive=True)
observer.start()
try:
    while True:
        time.sleep(1)
finally:
    observer.stop()
    observer.join()

Alternatively, you can use the observer as a context manager for cleaner code:

.. code-block:: python

import sys
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()
paths = sys.argv[1:] if len(sys.argv) > 1 else ["."]
for path in paths:
    observer.schedule(event_handler, path, recursive=True)

with observer:
    while True:
        time.sleep(1)

To run the script, pass the directories you want to monitor as command-line arguments (defaults to the current directory if omitted):

.. code-block:: bash

python script.py dir1 dir2

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 *.txt files while ignoring all directory events:

.. code-block:: bash

watchmedo log \
    --patterns='**/*.py;**/*.txt' \
    --ignore-directories \
    --recursive \
    --verbose \
    .

You can use the shell-command subcommand to execute shell commands in response to events:

.. code-block:: bash

watchmedo shell-command \
    --patterns='**/*.py;**/*.txt' \
    --recursive \
    --command='echo "${watch_src_path}"' \
    .

Please see the help information for these commands by typing:

.. code-block:: bash

watchmedo [command] --help

This is the beginning of the README. Read the rest at the original. Read the full README ↗