matplotlib · QuLogic · Jul 30, 2021 · Jul 21, 2021 · Jul 21, 2021 · Jul 22, 2021
diff --git a/doc/api/next_api_changes/development/20706-AP.rst b/doc/api/next_api_changes/development/20706-AP.rst
@@ -0,0 +1,4 @@
+Improve underscore support in LaTeX
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The `underscore <https://ctan.org/pkg/underscore>`_ package is now a requirement to improve support for underscores in LaTeX.
diff --git a/doc/devel/dependencies.rst b/doc/devel/dependencies.rst
@@ -221,9 +221,13 @@ Required:

 * a minimal working LaTeX distribution
 * `Graphviz <http://www.graphviz.org/download>`_
-* the LaTeX packages *cm-super* and *dvipng* (if your OS bundles TeXLive, the
+* the following LaTeX packages (if your OS bundles TeXLive, the
  "complete" version of the installer, e.g. "texlive-full" or "texlive-all",
-  will often automatically include these packages)
+  will often automatically include these packages):
+
+  * `cm-super <https://ctan.org/pkg/cm-super>`_
+  * `dvipng <https://ctan.org/pkg/dvipng>`_
+  * `underscore <https://ctan.org/pkg/underscore>`_

 Optional, but recommended:


diff --git a/lib/matplotlib/tests/test_usetex.py b/lib/matplotlib/tests/test_usetex.py
@@ -100,8 +100,22 @@ def test_usetex_packages(pkg):
                                  text.get_window_extent())


-def test_textcomp_full():
-    plt.rcParams["text.latex.preamble"] = r"\usepackage[full]{textcomp}"
+@pytest.mark.parametrize(
+    "latex_statement",
+    [r"\usepackage[full]{textcomp}", r"\usepackage{underscore}"],
+)
+def test_latex_pkg_already_loaded(latex_statement):
+    plt.rcParams["text.latex.preamble"] = latex_statement
    fig = plt.figure()
    fig.text(.5, .5, "hello, world", usetex=True)
    fig.canvas.draw()
+
+
+def test_usetex_with_underscore():
+    plt.rcParams["text.usetex"] = True
+    df = {"a_b": range(5)[::-1], "c": range(5)}
+    fig, ax = plt.subplots()
+    ax.plot("c", "a_b", data=df)
+    ax.legend()
+    ax.text(0, 0, "foo_bar", usetex=True)
+    plt.draw()
diff --git a/lib/matplotlib/texmanager.py b/lib/matplotlib/texmanager.py
@@ -174,6 +174,12 @@ def _get_preamble(self):
            # relies on a custom preamble to change the geometry.
            r"\usepackage[papersize=72in, margin=1in]{geometry}",
            self.get_custom_preamble(),
+            # Use `underscore` package to take care of underscores in text
+            # The [strings] option allows to use underscores in file names
+            r"\makeatletter"
+            r"\@ifpackageloaded{underscore}{}"
+            r"{\usepackage[strings]{underscore}}"
+            r"\makeatother",
            # textcomp is loaded last (if not already loaded by the custom
            # preamble) in order not to clash with custom packages (e.g.
            # newtxtext) which load it with different options.