{{ message }}
Repository navigation
[ENH]: WSL support #32381
Description
Problem
Actually it is not user-friendly to run Matplotlib on WSL.
Moreover, this answer python - Show matplotlib plots (and other GUI) in Ubuntu (WSL1 & WSL2) - Stack Overflow is outdated.
Since WSL2 implements the Wayland protocol and the OpenGL API, Matplolib should detect it is running on WSL and select automatically the right backend or raises an informative error message.
To detect WSL, we can rely on:
unamekernel- or the presence of
/etc/wsl-distribution.conf
For the backend, we can use:
- Qt Agg with PyQt5 and set the env
QT_QPA_PLATFORM=wayland(PySide2 seems to crash) - to be completed Qt6 GTK Vulkan...
QT_QPA_PLATFORM is mandatory since Qt is probably not able to detect WSL and select the right backend.
RESUME for USERS: YOU DON'T NEED X11 ! It should work out of the box !
Proposed solution
No response
Activity
tacaswell commentedon Sep 23, 2026
Matplotlib should definitely not be setting any ENVS ourselves and I'm very skeptical of adding any code that checks (effectively) what linux distribution we are in.
However, if the user needs to do a bit of extra config to get GUI windows to work under WSL we should document that someplace, probably in https://matplotlib.org/stable/users/explain/figure/backends.html#interactive-backends
scottshambaugh commentedon Sep 23, 2026
I'm happy to trial run the setup instructions on this. I will note that the VcXsrv setup in that stack overflow is not outdated, and still works - I set it up on a fresh WSL2 machine a few weeks ago. But an out-of-the box solution would be better, and we should document the setup here regardless.
FabriceSalvaire commentedon Sep 24, 2026
I did further test on WSL Ubuntu
matplotlib.use('QtAgg')requires pyside6 and doesn't need theQT_QPA_PLATFORMenv to be set. I guess Qt6 Platform Abstraction was improved...Matplotlib.use('QtCairo')also works but requirescairocffiMy Qt6 test was reproducible in a PowerShell terminal, thus the installation procedure is quite similar for Windows and WSL:
versus
Please note, that lambda users will read the quick start guide and not the Backend page which is full of (outdated) details...
Indeed, according to the Installation page,
uv add matplotlib pyside6is the way to go for 99.99% of your users on any platform !rcomer commentedon Sep 26, 2026
Note that the conda-forge recipe includes pyside6, so anyone following the conda instructions will automatically get that. Does pixi also pull from conda-forge?
rcomer commentedon Sep 26, 2026
Also note that we will be dropping support for pyside2 at the next release
https://matplotlib.org/devdocs/api/next_api_changes/development/31740_REC.html#pyside2-support
rcomer commentedon Sep 26, 2026
We actually have a specific section for MacOS in the installation guide, so I think it would be reasonable to also have a WSL section there.
https://matplotlib.org/devdocs/install/index.html#macos-notes