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