1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
|
.. include:: global.rst.inc
.. _installation:
Installation
============
|project_name| requires 3.9+ to work. See a list of :ref:`installation-dependencies`.
Installing from PyPI using pip
------------------------------
.. parsed-literal::
$ python -m pip install -U |project_name|
# or to install the watchmedo utility:
$ python -m pip install -U '|project_name|\[watchmedo]'
Installing from source tarballs
-------------------------------
.. parsed-literal::
$ wget -c https://pypi.python.org/packages/source/w/watchdog/watchdog-|project_version|.tar.gz
$ tar zxvf |project_name|-|project_version|.tar.gz
$ cd |project_name|-|project_version|
$ python -m pip install -e .
# or to install the watchmedo utility:
$ python -m pip install -e '.[watchmedo]'
Installing from the code repository
-----------------------------------
::
$ git clone --recursive git://github.com/gorakhargosh/watchdog.git
$ cd watchdog
$ python -m pip install -e .
# or to install the watchmedo utility:
$ python -m pip install -e '.[watchmedo]'
.. _installation-dependencies:
Dependencies
------------
|project_name| 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 | Windows | Linux 2.6 | macOS | BSD |
| Dependency (row) | | | Darwin | |
+=====================+=============+=============+========+=============+
| XCode_ | | | Yes | |
+---------------------+-------------+-------------+--------+-------------+
The following is a list of dependencies you need based on the operating system you are
using the ``watchmedo`` utility.
+---------------------+-------------+-------------+--------+-------------+
| Operating system | Windows | Linux 2.6 | macOS | BSD |
| Dependency (row) | | | Darwin | |
+=====================+=============+=============+========+=============+
| PyYAML_ | Yes | Yes | Yes | Yes |
+---------------------+-------------+-------------+--------+-------------+
Supported Platforms (and Caveats)
---------------------------------
|project_name| 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:
.. WARNING:: Differences between behaviors of these native API
are noted below.
Linux 2.6+
Linux kernel version 2.6 and later come with an API called inotify_
that programs can use to monitor file system events.
.. NOTE:: On most systems the maximum number of watches that can be
created per user is limited to ``8192``. |project_name| needs one
per directory to monitor. To change this limit, edit
``/etc/sysctl.conf`` and add::
fs.inotify.max_user_watches=16384
macOS
The Darwin kernel/OS X API maintains two ways to monitor directories
for file system events:
* kqueue_
* FSEvents_
|project_name| can use whichever one is available, preferring
FSEvents over ``kqueue(2)``. ``kqueue(2)`` uses open file descriptors for monitoring
and the current implementation uses
`macOS 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.
.. NOTE:: More information about how |project_name| uses ``kqueue(2)`` is noted
in `BSD Unix variants`_. Much of this information applies to
macOS as well.
_`BSD Unix variants`
BSD variants come with kqueue_ which programs can use to monitor
changes to open file descriptors. Because of the way ``kqueue(2)`` works,
|project_name| needs to open these files and directories in read-only
non-blocking mode and keep books about them.
|project_name| will automatically open file descriptors for all
new files/directories created and close those for which are deleted.
.. NOTE:: The maximum number of open file descriptor per process limit
on your operating system can hinder |project_name|'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
Windows Vista and later
The Windows API provides the ReadDirectoryChangesW_. |project_name|
currently contains implementation for a synchronous approach requiring
additional API functionality only available in Windows Vista and later.
.. NOTE:: Since renaming is not the same operation as movement
on Windows, |project_name| 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, |project_name|
may not be able to completely scan the moved directory
in order to successfully queue movement events for
files and directories within it.
.. NOTE:: Since the Windows API does not provide information about whether
an object is a file or a directory, delete events for directories
may be reported as a file deleted event.
OS Independent Polling
|project_name| also includes a fallback-implementation that polls
watched directories for changes by periodically comparing snapshots
of the directory tree.
|
