diff --git a/docs/quickstart.rst b/docs/quickstart.rst index 6af09eb648..42e213c889 100644 --- a/docs/quickstart.rst +++ b/docs/quickstart.rst @@ -116,6 +116,11 @@ To enable debug mode, use the ``--debug`` option. * Debugger is active! * Debugger PIN: nnn-nnn-nnn +.. note:: + When the reloader starts, you'll see a message like ``Restarting with stat`` or + ``Restarting with watchdog``. This indicates which file monitoring backend is being + used. See :doc:`server` for more details about reloader types. + See also: - :doc:`/server` and :doc:`/cli` for information about running in debug mode. diff --git a/docs/server.rst b/docs/server.rst index d6beb1d86d..411af13562 100644 --- a/docs/server.rst +++ b/docs/server.rst @@ -94,6 +94,52 @@ site is accessed. This is intended to make errors more visible initially while still allowing the server to handle errors on reload. +Understanding the Reloader +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +When running Flask in debug mode, the development server automatically reloads when you +change your code. You'll see a message indicating how the reloader is monitoring for +changes: + +.. code-block:: text + + * Restarting with stat + * Restarting with watchdog (inotify) + +Flask uses one of two reloader backends: + +**watchdog** - Efficient file system monitoring + Watches for file changes using your operating system's native file system events. + This is faster and more efficient than polling. Flask automatically uses watchdog + if it's installed. + + Install it for better performance: + + .. code-block:: text + + $ pip install watchdog + + The text in parentheses (like ``inotify``, ``windowsapi``, or ``kqueue``) shows + which operating system API watchdog is using. This is informational only and varies + by platform. + +**stat** - Fallback polling method + Checks files periodically for changes. This is the default when watchdog is not + installed. It works everywhere but uses more resources. + +In most cases, you don't need to worry about which reloader is being used - Flask +chooses the best option automatically. However, if you need to force a specific +reloader (for example, for debugging), you can do so: + +.. code-block:: python + + app.run(debug=True, reloader_type='stat') + +For more technical details about the reloader implementation, see the +`Werkzeug serving documentation +`_. + + In Code -------