matplotlib · tacaswell · Aug 19, 2022 · Aug 19, 2022 · jklymak · Aug 20, 2022
diff --git a/doc/users/next_whats_new/loggers.rst b/doc/users/next_whats_new/loggers.rst
@@ -0,0 +1,10 @@
+``set_loglevel`` can opt-out of manipulating logging handlers
+-------------------------------------------------------------
+
+It is now possible to configure the logging level of the Matplotilb standard
+library logger without also implicitly installing a handler via both
+`matplotlib.set_loglevel` and `matplotlib.pyplot.set_loglevel` ::
+
+  mpl.set_loglevel('debug', ensure_handler=False)
+  # or
+  plt.set_loglevel('debug', ensure_handler=False)
diff --git a/lib/matplotlib/__init__.py b/lib/matplotlib/__init__.py
@@ -230,27 +230,43 @@ def _ensure_handler():
     return handler
 
 
-def set_loglevel(level):
+def set_loglevel(level, *, ensure_handler=True):
     """
-    Set Matplotlib's root logger and root logger handler level, creating
-    the handler if it does not exist yet.
+    Configure Matplotlib's logging levels.
+
+    Matplotlib uses the standard library `logging` framework under the root
+    logger 'matplotlib'.  This is a helper function to:
+
+    - set Matplotlib's root logger level
+    - optionally set the root logger handler's level, creating the handler
+      if it does not exist yet
 
     Typically, one should call ``set_loglevel("info")`` or
     ``set_loglevel("debug")`` to get additional debugging information.
 
+    Users or applications that are installing their own logging handlers
+    may want to directly manipulate ``logging.getLogger('matplotlib')`` rather
+    than use this function.
+
     Parameters
     ----------
     level : {"notset", "debug", "info", "warning", "error", "critical"}
         The log level of the handler.
 
+    ensure_handler : bool
+        If True will ensure that there is a `logging.StreamHandler` added to
+        the matplotlib root logger and that its level matches the logger level.
+
     Notes
     -----
     The first time this function is called, an additional handler is attached
     to Matplotlib's root handler; this handler is reused every time and this
     function simply manipulates the logger and handler's level.
+
     """
     _log.setLevel(level.upper())
-    _ensure_handler().setLevel(level.upper())
+    if ensure_handler:
+        _ensure_handler().setLevel(level.upper())
 
 
 def _logged_cached(fmt, func=None):