Document automatic Wayland/Nvidia workaround in troubleshooting#1033
Open
niksirbi wants to merge 3 commits into
Open
Document automatic Wayland/Nvidia workaround in troubleshooting#1033niksirbi wants to merge 3 commits into
niksirbi wants to merge 3 commits into
Conversation
napari now sets QT_QPA_PLATFORM=xcb and PYOPENGL_PLATFORM=glx automatically at startup, so explain that most users need no action, and document the manual workaround for the IPython/Jupyter case where a Qt application is created before napari is imported. Add a stable (wayland-and-nvidia) anchor that the in-app warning links to, while keeping the original heading. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
github-actions
Bot
added
the
documentation
TimMonko
approved these changes
May 28, 2026
Contributor
TimMonko
left a comment
TimMonko
left a comment
There was a problem hiding this comment.
Absolutely lovely! Thank you!!!! 🤩
I left two comments, but you are more then welcome to do with them as you please. :)
Co-authored-by: Tim Monko <timmonko@gmail.com>
Author
|
Thanks both! Probably it make sense to wait till we settle on how napari/napari#9009 lands before this one gets merged, right? |
Contributor
Yep! And because you have the "Depends on" in the OP our CI blocks it :) |
Author
Good to know! I should start using that too. |
Author
|
I pushed an additional commit |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
References and relevant issues
Depends on napari/napari#9009
Related to napari/napari#8808
napari/napari#9009 makes napari automatically apply the Wayland/Nvidia startup workaround (setting
QT_QPA_PLATFORM=xcbandPYOPENGL_PLATFORM=glx), and adds an in-app warning for the cases it can't cover. That warning links to the troubleshooting section updated here (#wayland-and-nvidia). See that PRfor the full background.
Description
This PR updates the "Running napari on Wayland with Nvidia cards" troubleshooting section to reflect the new automatic workaround in napari/napari#9009:
naparicommand or a Python script) no longer need to do anything.import napari(e.g. in IPython or Jupyter when%gui qtruns first), the user must set the variables themselves before starting the session.(wayland-and-nvidia)=anchor that the in-app warning links to, while keeping the original heading so existing links don't break.