@@ -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
106135The builtin backends
@@ -291,33 +320,6 @@ Debugging the figure windows not showing
291320
292321Sometimes 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-
321323If you are using a Notebook or integrated development environment (see :ref: `notebooks-and-ides `),
322324please consult their documentation for debugging figures not working in their
323325environments.
0 commit comments