Python Watchdog 101: Track, Monitor, and React to File Changes

Monitoring file and directory changes is a common task in many Python applications, from automating workflows to managing logs. With the right tools, you can react to these changes in real time, ensuring your processes run smoothly and efficiently.

For Python developers, the Watchdog library is a lightweight and versatile solution for tracking file system events like creation, deletion, modification, and movement.

Whether you’re building a simple script to monitor your personal files or creating a robust application for automated workflows, this guide will show you how to get started with Watchdog.

In this article, you’ll walk through the essentials of using Watchdog in Python, including installation, basic functionality, and advanced use cases like monitoring multiple directories or filtering specific file types.

By the end, you’ll have a working example you can adapt to suit your own projects.

What is Python Watchdog?

Python Watchdog is a library designed to monitor file and directory changes in real time. It allows developers to track events like file creation, deletion, modification, and movement with minimal setup.

By combining simplicity with flexibility, Watchdog is a great tool for both beginners and experienced developers looking to streamline their workflows.

The library works across all major operating systems, including Windows, macOS, and Linux, making it highly portable for a variety of projects.

With core components like the Observer and FileSystemEventHandler, Watchdog allows you to define custom actions that trigger whenever specific file system events occur.

Key Features of Python Watchdog

The Watchdog library offers a variety of features to simplify file and directory monitoring. Its real-time tracking capabilities, cross-platform support, and flexibility make it a valuable tool for many Python projects. Here are a few of its standout features:

1. Real-Time Monitoring: Easily track file creation, modification, deletion, and movement events.

2. Customizable Event Handling: Define how your application reacts to specific file system changes.

3. Support for Multiple Directories: Monitor multiple folders simultaneously with minimal setup.

4. File Filtering Options: Focus on specific file types, like .txt or .log, to streamline event handling.

Installing Python Watchdog

Before installing Watchdog, it’s a good idea to manage your dependencies within an isolated environment, such as a virtual environment or a Conda environment. This helps prevent conflicts with other Python packages.

Getting started with Python Watchdog is easy, thanks to its availability on PyPI.

$ python -m pip install -U watchdog

For more advanced troubleshooting, refer to the official documentation on installing Watchdog.

Getting Started with Python Watchdog

Now that you’ve installed Python Watchdog, let’s dive into how to use it. This section will walk you through setting up a basic Watchdog script to monitor file and directory changes. By the end, you’ll have a working example that detects events like file creations, modifications, and deletions.

It’s helpful to know the basic components you’ll need for every Watchdog project:

1. Observer: The core component that monitors file system changes. Here, we’re using the Observer object.

2. Event Handler: A custom handler to define actions for specific events like file creation, deletion, or modification. Here, we’ll be extending the FileSystemEventHandler class.

3. Path to Monitor: The directory you want to watch for changes.

Step 1: Importing the Necessary Modules

The core components of Watchdog are the Observer and FileSystemEventHandler classes. These allow you to monitor file system changes and define custom actions for specific events. Here’s the basic import structure:

from watchdog.observers import Observer
from watchdog.events import FileSystemEventHandler
import time

Step 2: Create a Custom Event Handler

Define a custom event handler class by extending FileSystemEventHandler. This lets you specify actions for file system events like file creation, deletion, or modification:

class MyEventHandler(FileSystemEventHandler):
    def on_created(self, event):
        print(f"File created: {event.src_path}")

    def on_deleted(self, event):
        print(f"File deleted: {event.src_path}")

    def on_modified(self, event):
        print(f"File modified: {event.src_path}")

    def on_moved(self, event):
        print(f"File moved: {event.src_path} to {event.dest_path}")

Step 3: Set Up the Observer

The Observer watches for file system changes and calls your custom event handler when events occur. You’ll want to update the path with the directory to monitor:

if __name__ == "__main__":
    path = "."  # Directory to monitor (current directory in this case)
    event_handler = MyEventHandler()
    observer = Observer()
    observer.schedule(event_handler, path, recursive=True)

    # Start the observer
    observer.start()
    print(f"Monitoring directory: {path}")

    try:
        while True:
            time.sleep(1)
    except KeyboardInterrupt:
        observer.stop()
    observer.join()

Step 4: Run the Code

Save the script as watchdog_example.py and run it using Python:

$ python watchdog_example.py

The script will monitor the specified directory and log events to the console. Try creating, deleting, modifying, or moving files in the monitored directory to see Watchdog in action.

Advanced Use Cases

Once you’ve mastered the basics of Watchdog, you can extend its functionality to handle more complex scenarios. Here are some advanced use cases to unlock the full potential of this powerful library:

1. Monitoring Multiple Directories

If you need to track changes across multiple directories, Watchdog makes it easy by creating multiple observers or scheduling multiple paths for the same observer. Here’s how you can monitor multiple directories:

paths = ["./directory1", "./directory2"]
event_handler = MyEventHandler()

observer = Observer()

for path in paths:
    observer.schedule(event_handler, path, recursive=True)

observer.start()

try:
    while True:
        time.sleep(1)
except KeyboardInterrupt:
    observer.stop()
observer.join()

2. Filtering Specific File Types

For applications where you only need to monitor certain types of files (e.g., .txt or .csv), you can use event filtering logic in your handler. This technique is particularly useful for scenarios like tracking log files or filtering out temporary system files. For example:

class MyFilteredEventHandler(FileSystemEventHandler):
    def on_modified(self, event):
        if event.src_path.endswith(".txt"):
            print(f"Text file modified: {event.src_path}")

3. Logging File Changes to a File

Instead of printing events to the console, you can log them to a file for auditing purposes. Combine Watchdog with Python’s logging module:

import logging

logging.basicConfig(filename="file_changes.log", level=logging.INFO)

class MyLoggingEventHandler(FileSystemEventHandler):
    def on_any_event(self, event):
        logging.info(f"Event: {event.event_type}, Path: {event.src_path}")