From d4934aabb3f5cf30e230d61b7aa9ea70a4e9f9d1 Mon Sep 17 00:00:00 2001 From: commitWithTisha Date: Sun, 9 Nov 2025 00:20:45 -0600 Subject: [PATCH 1/2] docs: document reloader types and their terminal output --- docs/quickstart.rst | 5 +++++ docs/server.rst | 46 +++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 51 insertions(+) diff --git a/docs/quickstart.rst b/docs/quickstart.rst index 6af09eb648..ed0f53cb51 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..569c64d583 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 ------- From 929ffbc7a9033daeec12207e5e108b0f0f8b839e Mon Sep 17 00:00:00 2001 From: "pre-commit-ci-lite[bot]" <117423508+pre-commit-ci-lite[bot]@users.noreply.github.com> Date: Sun, 9 Nov 2025 06:28:59 +0000 Subject: [PATCH 2/2] [pre-commit.ci lite] apply automatic fixes --- docs/quickstart.rst | 4 ++-- docs/server.rst | 10 +++++----- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/quickstart.rst b/docs/quickstart.rst index ed0f53cb51..42e213c889 100644 --- a/docs/quickstart.rst +++ b/docs/quickstart.rst @@ -117,8 +117,8 @@ To enable debug mode, use the ``--debug`` option. * 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 + 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: diff --git a/docs/server.rst b/docs/server.rst index 569c64d583..411af13562 100644 --- a/docs/server.rst +++ b/docs/server.rst @@ -112,13 +112,13 @@ Flask uses one of two reloader backends: 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. @@ -135,7 +135,7 @@ reloader (for example, for debugging), you can do so: app.run(debug=True, reloader_type='stat') -For more technical details about the reloader implementation, see the +For more technical details about the reloader implementation, see the `Werkzeug serving documentation `_.