watchdog：Python 文件系统监控，它全包了

watchdog 在 GitHub 上已经有 7,363 颗星了。

这是一个 Python 库，专门干一件事：监控文件系统事件。文件被修改、新建、删除、移动，它都能抓到，你只需要写几行代码就能对这些变化做出反应。

1、为什么需要它

做自动化工具的人经常遇到的场景：监听一个目录，文件变了就触发操作。代码改了自动重载服务，日志文件新增了自动收集，上传目录有新文件自动处理。

这些问题看似简单，真要跨平台做好却不容易。Linux 用 inotify，macOS 用 FSEvents，Windows 用 ReadDirectoryChangesW，每种系统的底层机制都不一样。自己从头写，工作量不小。

watchdog 把这些全封装了。你不需要关心底层是哪个系统 API，统一接口就能用。

2、怎么用

核心概念很直观：一个 Observer 负责盯着目录，一个 EventHandler 负责处理事件。继承 FileSystemEventHandler，重写 on_any_event 或其他具体方法就行。

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

class MyHandler(FileSystemEventHandler):
    def on_any_event(self, event):
        print(event)

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

这段代码会监控当前目录下所有文件变化，把事件打印出来。

Python 3.9 以上版本还支持 context manager 写法，代码更简洁：

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

如果不想写代码，watchdog 还带了一个命令行工具 watchmedo，直接就能用。

3、watchmedo 命令行

watchmedo 提供了几个子命令。log 子命令可以打印文件事件日志：

watchmedo log --patterns='**/*.py' --recursive .

shell-command 子命令可以在文件变化时执行脚本：

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

tricks 功能更进一步，支持通过 YAML 配置文件定义事件响应规则，适合更复杂的自动化场景。

4、跨平台支持

watchdog 覆盖了主流操作系统：

• Linux：inotify
• macOS：FSEvents、kqueue
• FreeBSD/BSD：kqueue
• Windows：ReadDirectoryChangesW
• 任意系统：PollingObserver（轮询模式，不推荐但保持兼容）

如果用 kqueue，需要注意系统对文件描述符的限制，可能需要调整 ulimit。网络文件系统（CIFS）场景下，需要手动指定 PollingObserver。

5、安装与生态

安装很简单，一行命令：

pip install -U watchdog

如果需要 watchmedo 工具，可以安装带扩展的版本：

pip install -U 'watchdog[watchmedo]'

项目从 2011 年开始维护，经过十几年迭代，稳定性和社区成熟度都经过了充分验证。第三方应用如 Watchdog.app 基于它做了 macOS 图形界面，方便不写代码的用户使用。

如果你需要监听文件变化做自动化，watchdog 是目前 Python 生态里最成熟的选择。

分验证。第三方应用如 Watchdog.app 基于它做了 macOS 图形界面，方便不写代码的用户使用。

如果你需要监听文件变化做自动化，watchdog 是目前 Python 生态里最成熟的选择。