2026 napari 0.10.0: Alte Plugins am Mac abnehmen

Mit napari 0.10.0 wurde die Unterstützung für Qt5 entfernt. Nehmen Sie alte Plugins deshalb nicht durch ein direktes Überschreiben Ihrer Laborumgebung ab: Prüfen Sie sie zuerst in einer isolierten Umgebung mit Qt6 und testen Sie anschließend den vollständigen Analyseweg mit einer freigegebenen Bildprobe.

Dieser Ablauf ist für Sie gedacht, wenn Sie napari für biologische oder mikroskopische Bilder einsetzen und auf Plugins angewiesen sind.
Er unterstützt Sie auch, wenn Sie ein älteres Plugin warten oder die Analyseumgebung Ihres Labors verwalten.
Das Ziel ist eine nachvollziehbare Entscheidung: migrieren, mit Einschränkungen migrieren oder die bestehende Umgebung zunächst beibehalten.

Zuletzt geprüft am 02.11.2026 anhand der offiziellen Installationsdokumentation, der Release Notes zu napari 0.10.0 und der Dokumentation zur Plugin-Installation.

Vor dem Upgrade den tatsächlichen Arbeitsumfang erfassen

Ein Versionswechsel ist erst dann ein überschaubares Risiko, wenn klar ist, welche Bestandteile Ihrer Arbeit davon abhängen. Der Plugin-Name allein reicht für diese Entscheidung nicht: Ein Plugin kann in einem Projekt unverzichtbar sein, in einem anderen aber nur eine bequeme Zusatzfunktion liefern. Ebenso sagt ein erfolgreicher Programmstart nichts darüber aus, ob die verwendete Analyse noch funktioniert.

Legen Sie deshalb vor der Installation eine Inventur an. Halten Sie für jedes Plugin fest:

• Name, installierte Version und Installationsquelle;
• bekannte Qt-Abhängigkeiten, insbesondere Hinweise auf PyQt5 oder eine bereits unterstützte Qt6-Variante;
• Maintainer-Dokumentation, Release-Hinweise und bekannte Einschränkungen;
• die konkrete Aufgabe im Laborablauf und die Person, die das Ergebnis fachlich beurteilen kann;
• eine mögliche Alternative, falls die Funktion nicht rechtzeitig migriert werden kann.

Trennen Sie dabei Pflichtfunktionen von Komfortfunktionen. Ein Plugin, das für die Auswertung einer laufenden Studie erforderlich ist, darf nicht nach denselben Kriterien behandelt werden wie ein Werkzeug, dessen Ausfall sich durch einen manuellen Arbeitsschritt ausgleichen lässt. Gibt es keine ausdrückliche Kompatibilitätsaussage der Maintainer, vermerken Sie „ungeklärt“ und planen Sie einen Laufzeittest ein. Fehlende Dokumentation ist kein Beleg für Inkompatibilität – sie ist aber auch keine Freigabe.

Sichern Sie außerdem die Ausgangslage, bevor Sie etwas ändern. Ein Export der installierten Python-Pakete lässt sich mit python -m pip freeze erstellen; die pip-Dokumentation zu pip freeze beschreibt, wie die installierten Distributionen aufgelistet werden. Bewahren Sie diese Datei zusammen mit den bisherigen Startanweisungen und den projektrelevanten Plugin-Einstellungen auf. So können Sie bei einem fehlgeschlagenen Test nachvollziehen, welche Umgebung Sie vergleichen.

Die Gegenüberstellung hilft, den geeigneten Testweg festzulegen. Die Bewertungen sind eine Entscheidungshilfe für die Planung, keine Garantie für die Kompatibilität eines bestimmten Plugins.

Die Grenzen der eigenständigen Anwendung sind für die Planung entscheidend: Laut offizieller napari-Dokumentation zur Pluginsuche und -installation enthält die eigenständige Anwendung möglicherweise nicht alle Plugins. Wenn Ihr Projekt ein bestimmtes Plugin voraussetzt, werten Sie einen erfolgreichen Start der Anwendung daher höchstens als ersten Funktionstest.

Erster Schritt: Eine getrennte Qt6-Testumgebung vorbereiten

Verwenden Sie für die Abnahme eine Umgebung, die nicht von der laufenden Laborinstallation abhängt. Die offiziellen Installationshinweise für napari beschreiben die verfügbaren Installationswege. Für einen Plugin-Test, bei dem Python-Abhängigkeiten gezielt mit dem Projekt abgeglichen werden müssen, ist eine separate Python-Umgebung meist aussagekräftiger als die eigenständige Anwendung. Folgen Sie bei der konkreten Einrichtung den dort beschriebenen Schritten und halten Sie die Testumgebung getrennt von der Teamumgebung.

Achten Sie bei der Wahl des Qt-Backends darauf, nicht einfach die alte Installation in die neue Umgebung zu kopieren. Für napari 0.10.0 nennt die offizielle Dokumentation PyQt6 oder PySide6; PyQt5 kann für dieses Release nicht als Qt5-Backend weiterverwendet werden. Die Release Notes zu napari 0.10.0 sind die maßgebliche Referenz für die Änderungen dieses Releases. Installieren Sie Plugins erst, wenn die Basisinstallation startet und Sie das tatsächlich verwendete Backend geprüft haben.

Gehen Sie bei einer isolierten Einrichtung in dieser Reihenfolge vor:

1. Sichern Sie die Paketliste der bisherigen Umgebung und notieren Sie deren Startweg.
2. Richten Sie eine neue, klar benannte Testumgebung ein; verwenden Sie sie nicht für die reguläre Auswertung.
3. Installieren Sie napari nach der offiziellen Installationsanleitung und wählen Sie ein dort unterstütztes Qt6-Backend.
4. Starten Sie napari zunächst ohne projektspezifische Plugins. Damit trennen Sie einen Fehler der Basisinstallation von einem Plugin-Fehler.
5. Installieren Sie anschließend nur die für die Abnahme erforderlichen Plugins und halten Sie jeden Installationsschritt fest.
6. Prüfen Sie, ob Plugin-Erkennung, Laden und benötigte Oberfläche funktionieren, bevor Sie mit einer fachlichen Probe beginnen.

Dokumentieren Sie außerdem den Systemkontext. Dazu gehören macOS-Version, Prozessortyp und Installationsweg der Testumgebung. Bei einem Apple Silicon Mac kann ein Fehler durch eine nicht verfügbare oder unpassende Abhängigkeit entstehen; er beweist für sich allein nicht, dass die Hardware die Ursache ist. Prüfen Sie zunächst, ob das Plugin eine Qt5-Abhängigkeit mitbringt, ob eine Qt6-Version existiert und ob die Fehlermeldung auf ein fehlendes Paket, einen Importfehler oder einen Darstellungsfehler verweist.

Zweiter Schritt: Backend, Plugin-Erkennung und Oberfläche getrennt prüfen

Behandeln Sie die technische Prüfung als mehrere voneinander unabhängige Freigaben. Ein installierbares Paket kann beim Import scheitern; ein importierbares Plugin kann in napari nicht erscheinen; ein sichtbares Plugin kann beim Öffnen seiner Oberfläche oder bei einer bestimmten Aktion fehlerhaft reagieren. Wenn Sie diese Zustände getrennt protokollieren, wird die Fehlersuche deutlich präziser.

Prüfen Sie zunächst, welches Backend die laufende Umgebung tatsächlich verwendet. Eine kurze Abfrage kann Ihnen dabei helfen:

import napari
import qtpy

print(napari.__version__)
print(qtpy.API_NAME)

Der erste ausgegebene Wert identifiziert die napari-Version, der zweite die von qtpy erkannte Qt-API. Vergleichen Sie das Ergebnis mit der Installationsdokumentation und Ihren Umgebungsnotizen. Wenn die Abfrage selbst fehlschlägt, ist das bereits ein Befund zur Testumgebung; schließen Sie daraus nicht unmittelbar auf das Plugin.

Prüfen Sie danach jedes Pflicht-Plugin einzeln:

• Wird das Plugin in der Plugin-Auswahl oder in der erwarteten Oberfläche angezeigt?
• Lässt es sich laden, ohne dass ein Import- oder Abhängigkeitsfehler auftritt?
• Öffnet sich die für den Arbeitsablauf erforderliche Oberfläche?
• Funktioniert die für das Projekt benötigte Aktion mit der vorgesehenen Eingabe?
• Bleiben die erwarteten Einstellungen und Ergebnisse beim Export erhalten?

Dokumentieren Sie Fehlermeldungen vollständig, einschließlich des Installationsschritts, nach dem sie auftraten. Wenn ein Plugin beim Import an PyQt5-spezifischen Schnittstellen scheitert, vergleichen Sie diesen Befund mit der Abhängigkeitsliste und den Angaben des Plugin-Maintainers. Die Empfehlungen für napari-Plugin-Entwickler bieten dafür einen Anhaltspunkt, ersetzen aber nicht die Prüfung der konkreten Plugin-Version.

Bei einer ungewöhnlichen Darstellung oder einem Absturz sollten Sie die Umgebung reproduzierbar halten und zunächst den Fehler eingrenzen: Funktioniert napari ohne das Plugin? Tritt das Problem nur mit einer bestimmten Funktion auf? Liefert das Plugin selbst einen aussagekräftigen Fehler? Die offiziellen Hinweise zur napari-Fehlersuche helfen bei der weiteren Diagnose. Ein einzelner Importfehler ist kein Beleg dafür, dass alle alten Plugins inkompatibel sind; ebenso wenig genügt ein erfolgreicher Import, um ein Plugin für Forschungszwecke freizugeben.

Dritter Schritt: Den Forschungsablauf mit einer Bildprobe abnehmen

Führen Sie die fachliche Abnahme mit einem Datensatz durch, dessen Verwendung für Tests zulässig ist. Verwenden Sie keine vertraulichen oder personenbezogenen Forschungsdaten, wenn die Testumgebung dafür nicht freigegeben ist. Prüfen Sie vorher, welche Zugriffsrechte und Speicherorte für die Probe gelten, und halten Sie die Datenverarbeitung mit den Regeln Ihres Instituts in Einklang.

Wählen Sie eine Probe, die für die tatsächliche Arbeit repräsentativ ist. Sie sollte die Dateiformate, Bilddimensionen und Verarbeitungsschritte abbilden, die für Ihr Projekt relevant sind, ohne unnötige Forschungsdaten einzuschließen. Notieren Sie, welche Eingabedatei, Plugin-Aktion und Einstellungen verwendet werden. So können Sie den alten und neuen Lauf sinnvoll vergleichen, statt sich auf eine Erinnerung an frühere Ergebnisse zu verlassen.

Arbeiten Sie die kritischen Schritte nacheinander ab:

• Einlesen: Wird die Bilddatei geöffnet, und stimmen die erwarteten Kanäle, Ebenen und Metadaten?
• Darstellung: Werden die für die Beurteilung relevanten Ebenen so angezeigt, wie es der Projektablauf verlangt? Die napari-Dokumentation zu Layern erläutert, wie Ebenen im Viewer verwendet werden.
• Plugin-Aktion: Lässt sich die notwendige Segmentierung, Annotation oder Analyse mit den für Ihr Projekt vorgesehenen Einstellungen ausführen?
• Weiterverarbeitung: Bleiben Zwischenschritte, Annotationen und benötigte Parameter für die nächsten Arbeitsschritte verfügbar?
• Export: Entspricht das exportierte Ergebnis dem erwarteten Format und lässt es sich in den anschließenden Auswertungsschritten verwenden?

Vergleichen Sie anschließend die Ergebnisse mit der alten Umgebung. Prüfen Sie nicht nur, ob beide Fenster ähnlich aussehen: Gleichen Sie die fachlich relevanten Ausgaben ab und entscheiden Sie vorab, welche Unterschiede zulässig sind. Falls das Projekt eine bestimmte Auswertungslogik verlangt, beziehen Sie die fachlich verantwortliche Person in die Freigabe ein. Ein Programmstart ist ein technischer Test; er ist kein Nachweis dafür, dass ein Forschungsworkflow unverändert funktioniert.

Vierter Schritt: Entscheidung dokumentieren und Rückweg offenhalten

Nutzen Sie eine Checkliste, die technische und fachliche Ergebnisse getrennt festhält. Markieren Sie einen Punkt erst dann als erledigt, wenn die betreffende Prüfung in der Testumgebung tatsächlich durchgeführt und dokumentiert wurde.

• [ ] Ausgangsumgebung und Paketliste sind gesichert.
• [ ] Pflicht-Plugins und ihre Maintainer-Angaben sind erfasst.
• [ ] Die Testumgebung ist von der Teamumgebung getrennt.
• [ ] Qt6 wird in der Testumgebung als tatsächlich verwendetes Backend erkannt.
• [ ] Pflicht-Plugins werden gefunden und lassen sich laden.
• [ ] Erforderliche Plugin-Oberflächen und Aktionen funktionieren.
• [ ] Der repräsentative Bildablauf wurde bis zum Ergebnisexport durchgeführt.
• [ ] Ergebnisse wurden anhand vorher festgelegter fachlicher Kriterien verglichen.
• [ ] Einschränkungen, offene Fehler und ein Rückweg sind schriftlich festgehalten.

Entscheiden Sie danach anhand der Befunde, nicht allein anhand der Versionsnummer:

• Migration freigeben: Pflicht-Plugins funktionieren mit dem geprüften Qt6-Backend, und die relevanten Bildanalyse-Schritte erfüllen die Projektanforderungen. Planen Sie die Aktualisierung der Hauptumgebung trotzdem kontrolliert und bewahren Sie die alte Umgebung so lange als Rückweg auf, wie sie noch für laufende Arbeit benötigt wird.
• Mit Einschränkungen freigeben: Nicht kritische Funktionen fehlen oder verhalten sich anders, während der eigentliche Forschungsablauf die vereinbarten Kriterien erfüllt. Dokumentieren Sie, welche Funktionen betroffen sind und wie Anwenderinnen und Anwender damit umgehen sollen.
• Migration verschieben: Ein Pflicht-Plugin hängt von nicht verfügbaren Qt5-Komponenten ab, die benötigte Oberfläche funktioniert nicht oder die Ergebnisse bestehen die fachliche Abnahme nicht. Behalten Sie die bisherige Umgebung für den laufenden Ablauf bei und prüfen Sie erneut, wenn der Maintainer eine passende Anpassung veröffentlicht oder Sie eine belastbare Alternative finden.

Für die Teamübergabe sollte die Freigabenotiz den getesteten Installationsweg, das Qt-Backend, die Plugin-Versionen, den verwendeten Probedatensatz, die beobachteten Fehler und die Entscheidung enthalten. So kann eine andere Person die Abnahme nachvollziehen, statt den Zustand aus einer funktionierenden Installation ableiten zu müssen. Wenn Sie den Test an einem anderen Ort oder durch weitere Teammitglieder durchführen lassen, klären Sie vorher, wie Datenzugriff, Speicherung und Fernzugriff organisatorisch geregelt sind. Die Hinweise zur Datenschutz- und Datenverarbeitung bei CDNMac können Sie als Ausgangspunkt für die Prüfung der dort beschriebenen Datenschutzbedingungen heranziehen; die Freigabe sensibler Forschungsdaten muss dennoch zu den Vorgaben Ihrer Einrichtung passen.

Häufige Fragen zur Plugin-Abnahme

Qt5-Plugins und napari 0.10.0

PyQt5 kann in napari 0.10.0 nicht als Qt5-Backend verwendet werden, weil das Release die Qt5-Unterstützung entfernt hat. Daraus folgt nicht automatisch, dass jedes Plugin, das früher mit Qt5 eingesetzt wurde, ausgeschlossen ist. Entscheidend sind die tatsächlichen Abhängigkeiten und eine Prüfung mit dem vorgesehenen Qt6-Backend. Klären Sie ungeklärte Fälle über Maintainer-Angaben und einen isolierten Laufzeittest.

Fehlendes Plugin in der eigenständigen Anwendung

Die eigenständige napari-Anwendung kann Plugins auslassen, die in einer Python-Umgebung verfügbar wären. Prüfen Sie die offizielle Plugin-Dokumentation für den Installationsweg, den Sie verwenden. Wenn Ihr Pflicht-Plugin dort nicht verfügbar ist, wechseln Sie für die Abnahme zu einer getrennten Python-Umgebung. Bewerten Sie das Plugin erst nach dem dortigen Erkennungs- und Funktionstest, nicht anhand seines Fehlens in der eigenständigen Anwendung.

Älteres Plugin unter PyQt6 prüfen

Suchen Sie nach Hinweisen des Maintainers zu Qt6 und prüfen Sie die dokumentierten Abhängigkeiten auf Qt5-spezifische Komponenten. Installieren Sie das Plugin getrennt von der Laborumgebung und kontrollieren Sie Backend, Erkennung, Import und benötigte Oberfläche. Entscheidend ist anschließend, ob die konkrete Plugin-Funktion mit Ihren projektbezogenen Eingaben arbeitet. Ohne Maintainer-Aussage bleibt ein erfolgreicher Test eine Aussage zu Ihrer geprüften Kombination, nicht zu allen Installationen.

Bildanalyse-Ergebnisse nach dem Upgrade vergleichen

Wählen Sie eine für Tests freigegebene Probe und führen Sie dieselben wichtigen Schritte in alter und neuer Umgebung aus. Prüfen Sie den Import, die benötigte Plugin-Aktion, Annotationen, Einstellungen und den Export. Legen Sie vor dem Vergleich fest, welche fachlichen Kriterien erfüllt sein müssen, und halten Sie Abweichungen fest. Startet napari zwar, besteht aber der Ergebnisvergleich nicht, ist der Forschungsablauf noch nicht abgenommen.

Wenn kein eigener Mac verfügbar ist

Ein Laborrechner mit Linux oder Windows kann für viele Aufgaben weiter geeignet sein, bildet aber eine echte macOS-Desktopumgebung nicht ab. Ein gemeinsam genutzter Mac ist wiederum nur dann praktikabel, wenn Sie zur benötigten Zeit Zugang haben und die Testdaten dort gemäß den Regeln Ihrer Einrichtung verwenden dürfen. Ein eigener Kauf bindet Budget an Hardware, die nach Abschluss der Migration möglicherweise nicht regelmäßig gebraucht wird.

Wenn Ihre Abnahme eine interaktive macOS-Oberfläche erfordert und Ihnen kein geeigneter Mac zur Verfügung steht, können Sie prüfen, ob eine gemietete Mac-Umgebung zu Ihrem konkreten Plugin, Datenzugriff und Bedienungsbedarf passt. Kontrollieren Sie vorab, ob der vorgesehene Zugriff und die erforderliche Installation für Ihren Test geeignet sind; die Verfügbarkeit einer Mac-Umgebung allein garantiert keine Plugin-Kompatibilität oder fachliche Freigabe. Einen Überblick über die Nutzungsschritte bietet der Einstieg bei CDNMac; Bedingungen und Laufzeiten sollten Sie vor einer Entscheidung auf der Übersicht der CDNMac-Tarife prüfen.

Für einen einmaligen oder zeitlich begrenzten Qt6-Test kann dieses Vorgehen den Kauf eines eigenen Geräts vermeiden. Wenn Ihr Labor den Mac dagegen dauerhaft für umfangreiche Analysen, lokale Datenträger oder physische Anschlüsse benötigt, ist ein eigener, kontrollierbarer Rechner möglicherweise die passendere Lösung. Entscheidend bleibt, dass Sie die napari-Abnahme zuerst in einer isolierten Umgebung durchführen und erst nach dokumentiertem Funktionstest über die Migration Ihrer Hauptumgebung entscheiden.

Häufig gestellte Fragen