The napari 0.10.0 release notes confirm that Qt5 support was removed, so PyQt5 cannot serve as the Qt backend for this release (official release notes). Do not overwrite your lab’s current environment. Validate legacy plugins and a representative analysis workflow in an isolated environment with a Qt6 backend first. If a required plugin still depends on Qt5, retain the known-good environment or defer the upgrade until you have a workable migration path.
This guide is for graduate students and researchers using napari to analyze microscopy or biological images.
Plugin maintainers can use it to check Qt backend requirements and loading behavior.
Lab administrators can use the acceptance results to decide whether to migrate the shared environment or keep it unchanged.
Last updated November 2, 2026. Version and installation details were checked against napari’s installation guide, release notes, and plugin documentation.
Before the upgrade: record what your project depends on
Treat the current environment as a baseline, not as something to repair in place. Before changing packages, record how the lab launches napari, which Python environment it uses, and which plugins are required for active projects. This record lets you compare the candidate environment with the actual setup rather than relying on a successful application launch as proof of compatibility.
Create a short inventory for each plugin:
- Plugin name and version, as shown by the current environment or project documentation.
- Installation source, such as a package index, a source repository, or an institutional setup script.
- Any stated Qt dependency, including references to PyQt5, PyQt6, PySide6, or Qt-specific libraries.
- The task the plugin performs, such as segmentation, annotation, measurement, or data export.
- Whether the task is essential to a current study or has an acceptable alternative.
- Where the team can find the plugin maintainer’s compatibility notes and issue history.
Save the environment’s installed package list as part of this baseline. The pip freeze reference documents how to produce a list of installed distributions. Keep that record with the project notes, but do not assume it can recreate a working environment by itself: package availability, operating system details, and external data can also affect a setup.
Can a plugin that depends on PyQt5 run under napari 0.10.0? Not with PyQt5 acting as the Qt backend, because the release removed Qt5 support. That does not establish that every older plugin is incompatible: a plugin may have a newer release, may work through a supported backend, or may not depend on Qt directly. Check its maintainer’s notes and verify its actual behavior in the isolated environment.
The napari plugin development best practices provide maintainers with guidance on plugin design and support. Use the plugin’s own documentation and repository as the authority for its particular dependencies. If those materials do not state whether Qt6 is supported, mark compatibility as unverified rather than inferring it from the plugin’s age or name.
Prepare an isolated test environment
The next decision is how to install napari for the test. The official installation guide describes installation approaches that include a standalone application and a Python environment. Neither path is automatically the right one for every research project: the standalone app can be convenient for checking the application, while a Python environment may be needed when the project depends on a specific set of Python plugins.
| Test route | Useful for | Main limitation to check |
|---|---|---|
| Standalone application | Checking whether napari launches and testing plugins available through that app’s installation workflow | The app may not include a plugin your project needs; check the official plugin installation instructions |
| Clean Python environment | Testing napari alongside the Python packages and plugins required by a project | You must keep its dependencies separate from the lab’s existing environment and confirm which Qt backend is active |
| Existing lab environment | Comparing current behavior with the known baseline | It is not an isolated migration test; changes here can affect other users or studies |
Download or install the candidate version using the current napari installation instructions. Keep the test installation separate from the environment used for active work. If you choose a Python environment, create it specifically for the migration test, install the required packages there, and record the package state after setup. Do not add candidate packages to a shared environment just to see whether napari starts.
A standalone application may not provide every plugin your team uses. Why can the standalone napari app fail to show a particular plugin? The app can have a different set of installed packages from your project’s Python environment, and the plugin may need to be installed separately or may not be available through that path. Follow the official plugin installation guidance, then check whether the plugin is discoverable in the app. If your workflow needs project-specific Python dependencies, test in a clean Python environment instead of treating the standalone app as a complete replica.
If you need a Mac to run the test, first compare your requirements with the remote Mac use scenarios. Accessing a Mac remotely does not remove the need to check your institution’s data-handling rules, storage access, and interactive requirements. Your test environment still needs access to the permitted sample data and the plugin dependencies required for the project.
Confirm the Qt6 backend and test each plugin
A successful launch confirms only that the application can open. It does not prove that the intended Qt backend is active, that napari can discover the plugin, or that the plugin’s interface works. Verify those layers separately.
| Acceptance gate | Evidence to collect | If the gate fails |
|---|---|---|
| Qt backend | Confirm the active backend is PyQt6 or PySide6 | Inspect the test environment’s installed packages and setup |
| Plugin discovery | Confirm the plugin appears in napari’s plugin interface or is otherwise available as documented | Check installation location, package name, and discovery instructions |
| Plugin loading | Open the plugin and perform its normal startup action | Review the traceback and the plugin maintainer’s compatibility notes |
| Project task | Complete the required operation on a representative sample | Record the task as blocked or limited; do not approve migration based on launch alone |
For a Python-based test, you can inspect the backend reported by qtpy from the same environment used to launch napari:
python -c "from qtpy import API_NAME; print(API_NAME)"
The result should identify the Qt API used by that environment. The napari installation documentation describes the supported Qt6 backend choices, including PyQt6 and PySide6. Do not assume that installing a Qt6 package in a different environment changes the backend used by napari. Run the check from the test environment, then record the result with the environment details.
Next, check the plugin’s presence using napari’s plugin interface and the plugin’s own documented installation or activation procedure. If it does not appear, first verify that you installed it into the same environment that launches napari. Then check its package requirements and maintainer guidance. If the plugin appears but its interface fails, capture the exact error and consult the napari troubleshooting guide alongside the plugin’s own issue tracker or documentation.
How do you establish whether an older plugin supports PyQt6? Look for an explicit compatibility statement from its maintainer, release notes that mention the Qt backend, or a documented test setup. Then reproduce the plugin’s normal operation in the isolated environment. A dependency listing can reveal a PyQt5 requirement, but that alone may not describe every possible version or workaround. Treat missing maintainer guidance as uncertainty, not as proof of either compatibility or incompatibility.
A Qt import error on an Apple Silicon Mac is not enough to conclude that the hardware architecture caused the failure. Check the active environment, the installed Qt backend, and the plugin’s declared dependencies before changing architecture-specific settings.
This distinction matters when interpreting failures. A package may be missing, installed into a different environment, or incompatible with the selected Qt backend. Those are different problems and need different fixes. Record the exact command used to launch napari and the full error output before testing a dependency change. Avoid changing several packages at once; otherwise, you may not know which change altered the result.
Validate the research workflow with a representative sample
Use a sample that the project permits for testing. It should exercise the parts of the workflow that matter to the study, without exposing restricted or identifiable data unnecessarily. Compare the candidate environment with the current baseline using the same input and documented settings wherever possible.
Work through the project’s real sequence, rather than testing isolated buttons:
- Open the image or image collection using the project’s normal import route.
- Confirm that the required layers and image dimensions appear as expected. napari’s layers documentation explains the layer model; use the project’s own expected structure as the acceptance reference.
- Run each essential plugin operation, including the actions performed before and after it.
- Check annotations, measurements, or intermediate outputs that the project relies on.
- Export the result using the project’s normal format and destination.
- Compare the exported files and relevant measurements with the baseline, using the project’s existing acceptance criteria.
How do you check that the analysis result has not changed after the upgrade? Compare the candidate output with the output from the preserved environment using the project’s own criteria. Those may include expected labels, measurements, file structure, or review by the researcher responsible for the analysis. A matching application window is not evidence that the exported result is equivalent. If the workflow has no documented acceptance criteria, agree on them with the project owner before treating the test as a pass.
Keep a small test log with the environment description, backend result, plugin version, input sample identifier, actions performed, output location, and any difference from the baseline. Include screenshots or error logs only when they help someone reproduce the result. This makes it possible for another researcher or lab administrator to review the decision without relying on the tester’s memory.
An Apple Silicon Mac is part of the environment being tested, not a guarantee of compatibility. If you are validating on Apple Silicon, use the same plugin and workflow checks described above, and record any architecture-specific installation instructions required by the plugin maintainer. Do not generalize from one successful or failed plugin test to all napari plugins.
Decide whether to migrate, limit, or defer
After the checks, classify the result by what the project actually needs. A passing application launch is not enough to migrate a research environment; the required plugin operations and exported results must also meet the team’s criteria.
| Result | What it means | Recommended action |
|---|---|---|
| Pass | Required plugins load and the project’s essential workflow meets its acceptance criteria | Consider migrating after documenting the tested environment and rollback path |
| Limited pass | The core workflow works, but a nonessential plugin or feature is unavailable | Record the limitation and decide with the project owner whether an alternative is acceptable |
| Fail | A required plugin or analysis step cannot be completed or its output does not meet project criteria | Keep the known-good environment and defer the migration until the dependency or workflow is resolved |
Before approving a change to a shared environment, keep the old environment available and document how the team can return to it. Preserve the package record, launch instructions, and test outputs. If you use a managed lab setup, agree on who can change the environment and who signs off on the analysis result. This is especially important when several projects depend on the same plugin but use different versions or procedures.
Use this executable review before changing the team’s default environment:
- [ ] Record the current napari and plugin setup, including installation sources and launch method.
- [ ] Mark each plugin as essential, replaceable, or not currently used by the project.
- [ ] Confirm the candidate environment is isolated from active research work.
- [ ] Verify that the environment uses PyQt6 or PySide6 rather than PyQt5.
- [ ] Confirm each required plugin is discoverable and can open its required interface.
- [ ] Run the project’s representative image-analysis workflow from import through export.
- [ ] Compare candidate outputs with the baseline using project-approved criteria.
- [ ] Record limitations, maintainer guidance, and a rollback route before approving migration.
If a required plugin still depends on Qt5, or if a necessary workflow fails acceptance, keep the existing environment rather than forcing the upgrade. If only a nonessential feature is missing, document the gap and let the project owner decide whether the alternative is acceptable. Recheck the plugin maintainer’s documentation when a compatibility update becomes available.
When a remote Mac is worth evaluating
If your current option is a shared lab workstation, access may depend on other users’ schedules and the machine’s installed software. Buying and maintaining a dedicated Mac also creates an upfront cost and an ongoing support responsibility. A Linux or Windows workstation can be valuable for many research tasks, but it cannot by itself confirm how a macOS application behaves in a real macOS desktop environment.
A remote Mac can be a useful test route when you lack a local Mac and need an interactive macOS environment for plugin installation or image-workflow review. It is not automatically suitable for every dataset or project. Before choosing it, confirm that your institution permits the planned data access, that you can use the required interaction method, and that the environment can support the exact software and plugin combination you need to test. If the workflow depends on local peripherals or restricted data that cannot be accessed remotely, a remote session may not meet the requirement.
For setup and access considerations, review CDNMac’s getting-started guide. If the remote option fits your data policy and test procedure, compare the available terms on the plans page before choosing a rental period. Keep the decision tied to the acceptance task: rent access only when it gives you a way to run the plugin and validate the project workflow that your current Linux or Windows setup cannot verify.
Validate napari 0.10.0 on a Dedicated Mac
Use a dedicated CDNMac physical Mac to test napari 0.10.0 without changing your lab environment.