Skip to content

Commit 61e03f3

Browse files
committed
Move WSL backend guidance next to backend selection
1 parent c95e91d commit 61e03f3

1 file changed

Lines changed: 29 additions & 27 deletions

File tree

‎galleries/users_explain/figure/backends.rst‎

Lines changed: 29 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -101,6 +101,35 @@ Here is a detailed description of the configuration methods:
101101
use a different backend. Therefore, you should avoid explicitly calling
102102
`~matplotlib.use` unless absolutely necessary.
103103

104+
.. _wsl-backends:
105+
106+
Using Matplotlib with WSL
107+
^^^^^^^^^^^^^^^^^^^^^^^^^
108+
109+
WSL2 distributions can display Linux GUI applications through WSLg. When
110+
WSLg is available, it provides the display environment variables that GUI
111+
toolkits use, so Matplotlib can select an interactive backend in the same way
112+
as it does on other Linux systems. You do not need to install or configure
113+
an X server separately.
114+
115+
Make sure that a GUI toolkit supported by Matplotlib (for example, Qt or
116+
Tk) is installed in the WSL environment. If Matplotlib cannot find a usable
117+
interactive backend, check that WSLg is running and that ``DISPLAY`` or
118+
``WAYLAND_DISPLAY`` is set in the shell where Python is started. You can
119+
inspect the selected backend with:
120+
121+
.. code-block:: python3
122+
123+
import matplotlib
124+
125+
print(matplotlib.get_backend())
126+
127+
If no display is available (for example, when running a script in a headless
128+
WSL environment), select the non-interactive ``Agg`` backend and save figures
129+
to files instead. See :ref:`the-builtin-backends` for the available
130+
interactive backends and :ref:`selecting-a-backend` for ways to configure a
131+
backend explicitly.
132+
104133
.. _the-builtin-backends:
105134

106135
The builtin backends
@@ -291,33 +320,6 @@ Debugging the figure windows not showing
291320

292321
Sometimes things do not work as expected, usually during an install.
293322

294-
Using Matplotlib with WSL
295-
^^^^^^^^^^^^^^^^^^^^^^^^^
296-
297-
WSL2 distributions can display Linux GUI applications through WSLg. When
298-
WSLg is available, it provides the display environment variables that GUI
299-
toolkits use, so Matplotlib can select an interactive backend in the same way
300-
as it does on other Linux systems. You do not need to install or configure
301-
an X server separately.
302-
303-
Make sure that a GUI toolkit supported by Matplotlib (for example, Qt or
304-
Tk) is installed in the WSL environment. If Matplotlib cannot find a usable
305-
interactive backend, check that WSLg is running and that ``DISPLAY`` or
306-
``WAYLAND_DISPLAY`` is set in the shell where Python is started. You can
307-
inspect the selected backend with:
308-
309-
.. code-block:: python3
310-
311-
import matplotlib
312-
313-
print(matplotlib.get_backend())
314-
315-
If no display is available (for example, when running a script in a headless
316-
WSL environment), select the non-interactive ``Agg`` backend and save figures
317-
to files instead. See :ref:`the-builtin-backends` for the available
318-
interactive backends and :ref:`selecting-a-backend` for ways to configure a
319-
backend explicitly.
320-
321323
If you are using a Notebook or integrated development environment (see :ref:`notebooks-and-ides`),
322324
please consult their documentation for debugging figures not working in their
323325
environments.

0 commit comments

Comments
 (0)