Description

FabriceSalvaire

opened on Sep 23, 2026

Issue body actions

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:

• uname kernel
• 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

1. FabriceSalvaire

   added

   New feature

   on Sep 23, 2026
2. github-actions

   added

   first-contribution

   on Sep 23, 2026
3. tacaswell

   added

   Documentation: user guidefiles in galleries/users_explain or doc/usersfiles in galleries/users_explain or doc/users

   and removed

   New feature

   on Sep 23, 2026
4. tacaswell commented on Sep 23, 2026

   

   tacaswell

   on Sep 23, 2026

   Member

   More actions

   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
5. scottshambaugh commented on Sep 23, 2026

   

   scottshambaugh

   on Sep 23, 2026

   Contributor

   More actions

   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.
6. FabriceSalvaire commented on Sep 24, 2026

   

   FabriceSalvaire

   on Sep 24, 2026

   Author

   More actions

   I did further test on WSL Ubuntu

   • Matplolib Qt backend works with Qt6 (I missed this point for my first post...)
     • matplotlib.use('QtAgg') requires pyside6 and doesn't need the QT_QPA_PLATFORM env to be set. I guess Qt6 Platform Abstraction was improved...
     • Qt5 must be deprecated (it is no longer supported by Qt and we have Qt6)
     • pyside2 is not as good as PyQt5, but now pyside6 is fine and supported by Qt
     • Matplotlib.use('QtCairo') also works but requires cairocffi
   • the GTK backend is not a first choice alternative since it depends on pygobject that need to be compiled...
   • Notice that Tk and X11 are outdated solutions !!!

   My Qt6 test was reproducible in a PowerShell terminal, thus the installation procedure is quite similar for Windows and WSL:

   • install Python using winget
   • install Astral uv using the user manual procedure
   • start a fresh project
   • uv install matplolib and pyside6

   versus

   • install a WSL distribution (Python is already there)
   • install Astral uv using the user manual procedure
   • start a fresh project
   • uv install matplolib and pyside6

   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 pyside6 is the way to go for 99.99% of your users on any platform !
7. rcomer commented on Sep 26, 2026

   

   rcomer

   on Sep 26, 2026

   Member

   More actions

   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?
8. rcomer commented on Sep 26, 2026

   

   rcomer

   on Sep 26, 2026

   Member

   More actions

   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
9. rcomer commented on Sep 26, 2026

   

   rcomer

   on Sep 26, 2026

   Member

   More actions

   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

Issue actions