Skip to content

Document automatic Wayland/Nvidia workaround in troubleshooting #1033

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
niksirbi wants to merge 2 commits into
base: main
Choose a base branch
from
+21 −4
Open

Document automatic Wayland/Nvidia workaround in troubleshooting #1033

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
f7a68e5
Document automatic Wayland/Nvidia workaround in troubleshooting
niksirbi May 28, 2026
2b89052
Apply suggestions from code review
niksirbi May 28, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 21 additions & 4 deletions docs/troubleshooting.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,7 @@ menu or you're trying to save layers and can't find the plugin in the listed wri
plugin using the deprecated `npe1` engine.

You can check if this is the problem by installing `napari<=0.6.6` and turning off the `Use npe2 adaptor` setting
under `Preferences -> Plugins -> Use npe2 adaptor` and restarting napari.
under `Preferences -> Plugins -> Use npe2 adaptor` and restarting napari.
If this fixes your issue, you'll need reach out to the plugin developer to update their plugin in order to use it
with `napari>=0.7.0`.

Expand Down Expand Up @@ -99,11 +99,13 @@ If you meet an exception starting from `RuntimeError: Mix of local and non local
In some rare situations this solution may not fix the environment,
so you may need to recreate, as described in the first option.

(wayland-and-nvidia)=
Comment thread
niksirbi marked this conversation as resolved.

### Running napari on Wayland with Nvidia cards

The Nvidia driver is not yet fully ready for Wayland.
We found that on computers with Nvidia cards and a wayland-based desktop environment, napari fails to start with errors such as this:
The Nvidia driver is not yet fully ready for Wayland.
We found that on computers with Nvidia cards and a Wayland-based desktop environment, napari may fail to start with errors such as this:

```pytb
OpenGL.error.GLError: GLError(
err = 1280,
Expand All @@ -112,9 +114,24 @@ OpenGL.error.GLError: GLError(
result = b'OpenGL ES 3.2 NVIDIA 580.126.09'
)
```
The problem might be solved by setting following environment variables:

The problem can be worked around by forcing Qt to use X11 (via XWayland) and PyOpenGL to use GLX, by setting the following environment variables:

```sh
QT_QPA_PLATFORM=xcb
PYOPENGL_PLATFORM=glx
```

napari sets these variables automatically at startup, so launching via
the `napari` command or a Python script usually works without any action on your part.
napari only sets these variables _for the current session_ if you haven't, so your own values are always respected.

This automatic fix only works if napari is imported *before* any Qt application is created.
If a Qt application already exists (most commonly in IPython or Jupyter when `%gui qt` runs
before `import napari`), napari can't apply the workaround and prints a warning.
In that case, set the variables yourself before starting the IPython or Jupyter session:

```sh
QT_QPA_PLATFORM=xcb PYOPENGL_PLATFORM=glx ipython
QT_QPA_PLATFORM=xcb PYOPENGL_PLATFORM=glx jupyter lab
```
Loading