| Server IP : 54.37.205.81 / Your IP : 216.73.216.76 Web Server : nginx/1.22.1 System : Linux vps-249481fa 6.1.0-50-cloud-amd64 #1 SMP PREEMPT_DYNAMIC Debian 6.1.176-1 (2026-07-02) x86_64 User : debian ( 1000) PHP Version : 8.2.32 Disable Function : NONE MySQL : OFF | cURL : ON | WGET : ON | Perl : ON | Python : OFF | Sudo : ON | Pkexec : OFF Directory : /usr/share/doc/python3-watchdog/html/ |
Upload File : |
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />
<title>Installation — watchdog 2.2.1 documentation</title>
<link rel="stylesheet" type="text/css" href="_static/pygments.css" />
<link rel="stylesheet" type="text/css" href="_static/pyramid.css" />
<script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script>
<script src="_static/jquery.js"></script>
<script src="_static/underscore.js"></script>
<script src="_static/_sphinx_javascript_frameworks_compat.js"></script>
<script src="_static/doctools.js"></script>
<script src="_static/sphinx_highlight.js"></script>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="next" title="Quickstart" href="quickstart.html" />
<link rel="prev" title="Watchdog" href="index.html" />
<!--[if lte IE 6]>
<link rel="stylesheet" href="_static/ie6.css" type="text/css" media="screen" charset="utf-8" />
<![endif]-->
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="quickstart.html" title="Quickstart"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="index.html" title="Watchdog"
accesskey="P">previous</a> |</li>
<li class="nav-item nav-item-0"><a href="index.html">watchdog 2.2.1 documentation</a> »</li>
<li class="nav-item nav-item-this"><a href="">Installation</a></li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<section id="installation">
<span id="id1"></span><h1>Installation<a class="headerlink" href="#installation" title="Permalink to this heading">¶</a></h1>
<p><code class="docutils literal notranslate"><span class="pre">watchdog</span></code> requires 3.6+ to work. See a list of <a class="reference internal" href="#installation-dependencies"><span class="std std-ref">Dependencies</span></a>.</p>
<section id="installing-from-pypi-using-pip">
<h2>Installing from PyPI using pip<a class="headerlink" href="#installing-from-pypi-using-pip" title="Permalink to this heading">¶</a></h2>
<pre class="literal-block">$ python -m pip install -U <code class="docutils literal notranslate"><span class="pre">watchdog</span></code>
# or to install the watchmedo utility:
$ python -m pip install -U <code class="docutils literal notranslate"><span class="pre">watchdog</span></code>[watchmedo]</pre>
</section>
<section id="installing-from-source-tarballs">
<h2>Installing from source tarballs<a class="headerlink" href="#installing-from-source-tarballs" title="Permalink to this heading">¶</a></h2>
<pre class="literal-block">$ wget -c <a class="reference external" href="https://pypi.python.org/packages/source/w/watchdog/watchdog">https://pypi.python.org/packages/source/w/watchdog/watchdog</a>-2.2.1.tar.gz
$ tar zxvf <code class="docutils literal notranslate"><span class="pre">watchdog</span></code>-2.2.1.tar.gz
$ cd <code class="docutils literal notranslate"><span class="pre">watchdog</span></code>-2.2.1
$ python -m pip install -e .
# or to install the watchmedo utility:
$ python -m pip install -e ".[watchmedo]"</pre>
</section>
<section id="installing-from-the-code-repository">
<h2>Installing from the code repository<a class="headerlink" href="#installing-from-the-code-repository" title="Permalink to this heading">¶</a></h2>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ 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]"
</pre></div>
</div>
</section>
<section id="dependencies">
<span id="installation-dependencies"></span><h2>Dependencies<a class="headerlink" href="#dependencies" title="Permalink to this heading">¶</a></h2>
<p><code class="docutils literal notranslate"><span class="pre">watchdog</span></code> 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.</p>
<table class="docutils align-default">
<colgroup>
<col style="width: 31%" />
<col style="width: 19%" />
<col style="width: 19%" />
<col style="width: 12%" />
<col style="width: 19%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head"><p>Operating system
Dependency (row)</p></th>
<th class="head"><p>Windows</p></th>
<th class="head"><p>Linux 2.6</p></th>
<th class="head"><p>macOS
Darwin</p></th>
<th class="head"><p>BSD</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p><a class="reference external" href="https://developer.apple.com/technologies/tools/xcode.html">XCode</a></p></td>
<td></td>
<td></td>
<td><p>Yes</p></td>
<td></td>
</tr>
</tbody>
</table>
<p>The following is a list of dependencies you need based on the operating system you are
using the <code class="docutils literal notranslate"><span class="pre">watchmedo</span></code> utility.</p>
<table class="docutils align-default">
<colgroup>
<col style="width: 31%" />
<col style="width: 19%" />
<col style="width: 19%" />
<col style="width: 12%" />
<col style="width: 19%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head"><p>Operating system
Dependency (row)</p></th>
<th class="head"><p>Windows</p></th>
<th class="head"><p>Linux 2.6</p></th>
<th class="head"><p>macOS
Darwin</p></th>
<th class="head"><p>BSD</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p><a class="reference external" href="https://www.pyyaml.org/">PyYAML</a></p></td>
<td><p>Yes</p></td>
<td><p>Yes</p></td>
<td><p>Yes</p></td>
<td><p>Yes</p></td>
</tr>
</tbody>
</table>
<section id="installing-dependencies">
<h3>Installing Dependencies<a class="headerlink" href="#installing-dependencies" title="Permalink to this heading">¶</a></h3>
<p>The <code class="docutils literal notranslate"><span class="pre">watchmedo</span></code> script depends on <a class="reference external" href="https://www.pyyaml.org/">PyYAML</a> which links with <a class="reference external" href="https://pyyaml.org/wiki/LibYAML">LibYAML</a>.
On macOS, you can use <a class="reference external" href="https://brew.sh/">homebrew</a> to install LibYAML:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">brew</span> <span class="n">install</span> <span class="n">libyaml</span>
</pre></div>
</div>
<p>On Linux, use your favorite package manager to install LibYAML. Here’s how you
do it on Ubuntu:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">sudo</span> <span class="n">apt</span> <span class="n">install</span> <span class="n">libyaml</span><span class="o">-</span><span class="n">dev</span>
</pre></div>
</div>
<p>On Windows, please install <a class="reference external" href="https://www.pyyaml.org/">PyYAML</a> using the binaries they provide.</p>
</section>
</section>
<section id="supported-platforms-and-caveats">
<h2>Supported Platforms (and Caveats)<a class="headerlink" href="#supported-platforms-and-caveats" title="Permalink to this heading">¶</a></h2>
<p><code class="docutils literal notranslate"><span class="pre">watchdog</span></code> 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:</p>
<div class="admonition warning">
<p class="admonition-title">Warning</p>
<p>Differences between behaviors of these native API
are noted below.</p>
</div>
<dl>
<dt>Linux 2.6+</dt><dd><p>Linux kernel version 2.6 and later come with an API called <a class="reference external" href="https://linux.die.net/man/7/inotify">inotify</a>
that programs can use to monitor file system events.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>On most systems the maximum number of watches that can be
created per user is limited to <code class="docutils literal notranslate"><span class="pre">8192</span></code>. <code class="docutils literal notranslate"><span class="pre">watchdog</span></code> needs one
per directory to monitor. To change this limit, edit
<code class="docutils literal notranslate"><span class="pre">/etc/sysctl.conf</span></code> and add:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">fs</span><span class="o">.</span><span class="n">inotify</span><span class="o">.</span><span class="n">max_user_watches</span><span class="o">=</span><span class="mi">16384</span>
</pre></div>
</div>
</div>
</dd>
<dt>macOS</dt><dd><p>The Darwin kernel/OS X API maintains two ways to monitor directories
for file system events:</p>
<ul class="simple">
<li><p><a class="reference external" href="https://www.freebsd.org/cgi/man.cgi?query=kqueue&sektion=2">kqueue</a></p></li>
<li><p><a class="reference external" href="https://developer.apple.com/library/mac/#documentation/Darwin/Conceptual/FSEvents_ProgGuide/Introduction/Introduction.html">FSEvents</a></p></li>
</ul>
<p><code class="docutils literal notranslate"><span class="pre">watchdog</span></code> can use whichever one is available, preferring
FSEvents over <code class="docutils literal notranslate"><span class="pre">kqueue(2)</span></code>. <code class="docutils literal notranslate"><span class="pre">kqueue(2)</span></code> uses open file descriptors for monitoring
and the current implementation uses
<a class="reference external" href="https://developer.apple.com/library/ios/#documentation/Performance/Conceptual/FileSystem/Articles/TrackingChanges.html">macOS File System Monitoring Performance Guidelines</a> to open
these file descriptors only to monitor events, thus allowing
OS X to unmount volumes that are being watched without locking them.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>More information about how <code class="docutils literal notranslate"><span class="pre">watchdog</span></code> uses <code class="docutils literal notranslate"><span class="pre">kqueue(2)</span></code> is noted
in <a class="reference internal" href="#bsd-unix-variants">BSD Unix variants</a>. Much of this information applies to
macOS as well.</p>
</div>
</dd>
<dt><span class="target" id="bsd-unix-variants">BSD Unix variants</span></dt><dd><p>BSD variants come with <a class="reference external" href="https://www.freebsd.org/cgi/man.cgi?query=kqueue&sektion=2">kqueue</a> which programs can use to monitor
changes to open file descriptors. Because of the way <code class="docutils literal notranslate"><span class="pre">kqueue(2)</span></code> works,
<code class="docutils literal notranslate"><span class="pre">watchdog</span></code> needs to open these files and directories in read-only
non-blocking mode and keep books about them.</p>
<p><code class="docutils literal notranslate"><span class="pre">watchdog</span></code> will automatically open file descriptors for all
new files/directories created and close those for which are deleted.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>The maximum number of open file descriptor per process limit
on your operating system can hinder <code class="docutils literal notranslate"><span class="pre">watchdog</span></code>’s ability to
monitor files.</p>
<p>You should ensure this limit is set to at least <strong>1024</strong>
(or a value suitable to your usage). The following command
appended to your <code class="docutils literal notranslate"><span class="pre">~/.profile</span></code> configuration file does
this for you:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">ulimit</span> <span class="o">-</span><span class="n">n</span> <span class="mi">1024</span>
</pre></div>
</div>
</div>
</dd>
<dt>Windows Vista and later</dt><dd><p>The Windows API provides the <a class="reference external" href="https://docs.microsoft.com/windows/win32/api/winbase/nf-winbase-readdirectorychangesw">ReadDirectoryChangesW</a>. <code class="docutils literal notranslate"><span class="pre">watchdog</span></code>
currently contains implementation for a synchronous approach requiring
additional API functionality only available in Windows Vista and later.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>Since renaming is not the same operation as movement
on Windows, <code class="docutils literal notranslate"><span class="pre">watchdog</span></code> tries hard to convert renames to
movement events. Also, because the <a class="reference external" href="https://docs.microsoft.com/windows/win32/api/winbase/nf-winbase-readdirectorychangesw">ReadDirectoryChangesW</a>
API function returns rename/movement events for directories
even before the underlying I/O is complete, <code class="docutils literal notranslate"><span class="pre">watchdog</span></code>
may not be able to completely scan the moved directory
in order to successfully queue movement events for
files and directories within it.</p>
</div>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>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.</p>
</div>
</dd>
<dt>OS Independent Polling</dt><dd><p><code class="docutils literal notranslate"><span class="pre">watchdog</span></code> also includes a fallback-implementation that polls
watched directories for changes by periodically comparing snapshots
of the directory tree.</p>
</dd>
</dl>
</section>
</section>
<div class="clearer"></div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<div>
<h3><a href="index.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Installation</a><ul>
<li><a class="reference internal" href="#installing-from-pypi-using-pip">Installing from PyPI using pip</a></li>
<li><a class="reference internal" href="#installing-from-source-tarballs">Installing from source tarballs</a></li>
<li><a class="reference internal" href="#installing-from-the-code-repository">Installing from the code repository</a></li>
<li><a class="reference internal" href="#dependencies">Dependencies</a><ul>
<li><a class="reference internal" href="#installing-dependencies">Installing Dependencies</a></li>
</ul>
</li>
<li><a class="reference internal" href="#supported-platforms-and-caveats">Supported Platforms (and Caveats)</a></li>
</ul>
</li>
</ul>
</div>
<div>
<h4>Previous topic</h4>
<p class="topless"><a href="index.html"
title="previous chapter">Watchdog</a></p>
</div>
<div>
<h4>Next topic</h4>
<p class="topless"><a href="quickstart.html"
title="next chapter">Quickstart</a></p>
</div>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="_sources/installation.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
<input type="submit" value="Go" />
</form>
</div>
</div>
<script>document.getElementById('searchbox').style.display = "block"</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="quickstart.html" title="Quickstart"
>next</a> |</li>
<li class="right" >
<a href="index.html" title="Watchdog"
>previous</a> |</li>
<li class="nav-item nav-item-0"><a href="index.html">watchdog 2.2.1 documentation</a> »</li>
<li class="nav-item nav-item-this"><a href="">Installation</a></li>
</ul>
</div>
<div class="footer" role="contentinfo">
© Copyright 2010-2023, Yesudeep Mangalapilly and contributors.
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 5.3.0.
</div>
</body>
</html>