watchdog requires Python 2.5 or above to work. If you are using a Linux/FreeBSD/Mac OS X system, you already have Python installed. However, you may wish to upgrade your system to Python 2.7 at least, because this version comes with updates that can reduce compatibility problems. See a list of Dependencies.
$ pip install watchdog
$ wget -c http://pypi.python.org/packages/source/w/watchdog/watchdog-0.5.4.tar.gz $ tar zxvf watchdog-0.5.4.tar.gz $ cd watchdog-0.5.4 $ python setup.py install
$ git clone --recursive git://github.com/gorakhargosh/watchdog.git $ cd watchdog $ python setup.py install
watchdog depends on many libraries to do its job. The following is a list of dependencies you need based on the operating system you are using.
|Operating system Dependency (row)||Windows||Linux 2.6||
|select_backport (Python 2.5/2.6)||Yes||Yes|
|a lot of luck||Yes|
brew install libyaml
On Linux, use your favorite package manager to install LibYAML. Here’s how you do it on Ubuntu:
sudo aptitude install libyaml-dev
On Windows, please install PyYAML using the binaries they provide.
watchdog uses native APIs as much as possible falling back to polling the disk periodically to compare directory snapshots only when it cannot use an API natively-provided by the underlying operating system. The following operating systems are currently supported:
Differences between behaviors of these native API are noted below.
The Darwin kernel/OS X API maintains two ways to monitor directories for file system events:
watchdog can use whichever one is available, preferring FSEvents over kqueue(2). kqueue(2) uses open file descriptors for monitoring and the current implementation uses Mac OS X File System Monitoring Performance Guidelines to open these file descriptors only to monitor events, thus allowing OS X to unmount volumes that are being watched without locking them.
More information about how watchdog uses kqueue(2) is noted in BSD Unix variants. Much of this information applies to Mac OS X as well.
BSD variants come with kqueue which programs can use to monitor changes to open file descriptors. Because of the way kqueue(2) works, watchdog needs to open these files and directories in read-only non-blocking mode and keep books about them.
watchdog will automatically open file descriptors for all new files/directories created and close those for which are deleted.
The maximum number of open file descriptor per process limit on your operating system can hinder watchdog‘s ability to monitor files.
You should ensure this limit is set to at least 1024 (or a value suitable to your usage). The following command appended to your ~/.profile configuration file does this for you:
ulimit -n 1024
The Windows API on Windows XP provides the ReadDirectoryChangesW function, which operates in either synchronous or asynchronous mode. watchdog contains implementations for both approaches.
The asynchronous I/O implementation is more scalable, does not depend entirely only on Python threads, and is hence preferred over the synchronous blocking version, which watchdog isolates from your main thread using Python threads so that your programs do not block.
Since renaming is not the same operation as movement on Windows, watchdog tries hard to convert renames to movement events. Also, because the ReadDirectoryChangesW API function returns rename/movement events for directories even before the underlying I/O is complete, watchdog may not be able to completely scan the moved directory in order to successfully queue movement events for files and directories within it.
watchdog also includes a fallback-implementation that polls watched directories for changes by periodically comparing snapshots of the directory tree.
Windows caveats again.
Because Windows has no concept of inodes as Unix-y platforms do, there is no current reliable way of determining file/directory movement on Windows without help from the Windows API.
You can use hashing for only those files in which you are interested in your event handlers to determine this, although it is rather slow. watchdog does not attempt to handle this on Windows. It is left to your discretion.