2026년 napari 0.10.0: 오래된 플러그인은 맥에서 어떻게 검수하나요?

이번 주에는 기존 환경을 보존하고 격리 검수부터 시작하세요

napari 0.10.0 릴리스 노트에는 Qt5 지원이 제거됐다고 명시되어 있습니다. 따라서 napari 0.10.0 맥 구형 플러그인 검수는 기존 연구 환경을 덮어쓰지 말고, Qt6 격리 환경에서 필수 플러그인과 분석 흐름을 확인하는 방식으로 진행해야 합니다. 플러그인이 Qt5에 의존하거나 독립 앱에 필요한 플러그인이 없으면, 의존성을 확인한 뒤 이전·보류·대체 도구 사용 여부를 결정하세요. 공식 릴리스 노트는 Qt5 지원 제거를 확인하는 기준 자료입니다.

이 글은 이런 경우에 적합합니다.
- napari 플러그인으로 현미경 또는 생물 이미지를 분석하는 대학원생
- 구형 플러그인이나 연구용 분석 환경을 유지하는 개발자
- 연구실의 이미지 분석 작업 흐름을 관리하고 업그레이드를 결정하는 관리자

마지막 업데이트: 2026년 11월 2일. 버전과 설치 경로는 napari 공식 설치 문서, 플러그인 설치 안내, 프로젝트 릴리스 자료를 기준으로 확인했습니다. 특정 플러그인의 호환 여부는 플러그인 관리자의 안내와 직접 실행 결과로 따로 판단해야 합니다.

업그레이드 전: 어떤 플러그인과 분석 단계가 꼭 필요한지 기록합니다

먼저 현재 환경을 재현할 수 있도록 정보를 남기세요. 플러그인 이름만 적으면 버전이나 설치 경로 차이 때문에 같은 결과를 다시 얻기 어려울 수 있습니다. Python 환경에서는 아래 명령으로 설치 패키지 목록을 저장할 수 있습니다. 사용법은 pip freeze 문서를 참고하세요.

python -m pip freeze > requirements-before.txt

이 목록만으로 플러그인이 Qt5에 의존하는지 확정할 수는 없습니다. 플러그인의 설치 문서와 저장소에서 PyQt5, PyQt6, PySide6, qtpy 등 Qt 관련 의존성을 확인하고, 유지 관리자가 밝힌 호환 범위와 최근 변경 내역을 함께 살펴보세요. 호환 안내가 없다면 “작동할 것”이라고 가정하지 말고 실제 검수 항목에 넣습니다. napari가 제공하는 플러그인 개발 권장 사항은 플러그인 호환성 판단의 참고 자료로 활용할 수 있습니다.

필수 플러그인과 편의 기능도 구분하세요. 분석 결과를 만드는 플러그인, 프로젝트 파일을 여는 플러그인, 일상 작업을 빠르게 해 주는 플러그인은 실패했을 때의 영향이 다릅니다. 프로젝트에 필요한 입력 데이터, 주요 조작, 저장 형식도 함께 기록해야 합니다.

격리 환경 준비: 독립 앱과 Python 환경을 목적에 맞게 고릅니다

napari 공식 설치 안내에 나온 독립 앱과 Python 설치 경로는 같은 목적에 쓰는 선택지가 아닙니다. 독립 앱은 실행을 빠르게 확인하기 편하지만, 필요한 플러그인이 기본으로 들어 있다고 볼 수 없습니다. 설치한 플러그인이 보이지 않는다면 앱의 플러그인 안내와 설치 경로를 확인하세요. Python 환경은 의존성을 명시해 플러그인과 함께 시험하기에 적합합니다. 설치 선택은 공식 설치 문서와 독립 앱의 플러그인 설치 안내를 기준으로 하세요.

python -m venv napari-test
source napari-test/bin/activate
python -m pip install --upgrade pip
python -m pip install "napari[all]"

위 명령은 격리된 Python 환경을 만드는 예시입니다. napari[all] 설치가 특정 연구실 플러그인까지 설치하거나 해당 플러그인의 호환성을 보장하는 것은 아닙니다. 플러그인별 설치 지침을 따르고, 실제 연구에 쓰는 환경과 시험 환경을 혼합하지 마세요. Apple Silicon 맥에서 오류가 발생해도 칩 종류만으로 원인을 단정하지 마세요. Qt 의존성, 플러그인 버전, 설치된 패키지의 조합을 나눠 확인해야 합니다.

Qt6 백엔드와 플러그인을 따로 확인합니다

napari 0.10.0에서는 PyQt5를 Qt 백엔드로 사용할 수 없습니다. 공식 설치 안내가 제시하는 Qt6 계열 백엔드는 PyQt6 또는 PySide6입니다. 이는 모든 구형 플러그인이 작동하지 않는다는 뜻은 아닙니다. 플러그인이 Qt5 전용 의존성을 직접 사용한다면 문제가 될 수 있고, Qt6에 맞게 업데이트됐거나 해당 의존성이 없다면 실행 가능성을 별도로 검수해야 합니다.

구형 플러그인은 PyQt5 환경에서 그대로 쓸 수 있나요?

napari 0.10.0의 Qt 백엔드로 PyQt5를 계속 사용하는 방식은 지원되지 않습니다. 다만 플러그인의 실제 호환 여부는 플러그인 코드와 의존성에 따라 다르므로, “오래된 플러그인”이라는 이유만으로 전부 불가능하다고 결론 내리면 안 됩니다. 관리자가 PyQt6 또는 PySide6 지원을 안내했는지 확인하고 격리 환경에서 검증하세요.

Qt6에서 플러그인을 확인하는 순서

먼저 현재 Python 환경에서 선택된 Qt 바인딩을 출력합니다.

python -c "from qtpy import API_NAME, QT_VERSION; print(API_NAME, QT_VERSION)"

출력에서 PyQt6 또는 PySide6 계열이 선택됐는지 확인합니다. 그다음 napari를 실행해 플러그인이 목록에 나타나는지, 불러올 때 오류가 나는지, 필요한 창과 조작 기능이 작동하는지 확인하세요. 플러그인이 발견되지 않으면 설치한 Python 환경이 실행 환경과 같은지, 플러그인 설치가 해당 환경에 적용됐는지부터 점검합니다. 오류가 계속되면 공식 문제 해결 안내와 플러그인 관리자의 설치 자료를 대조하세요.

독립 앱에서 플러그인이 보이지 않는 이유는 무엇인가요?

독립 앱에 모든 플러그인이 포함되는 것은 아닙니다. 플러그인 문서에 안내된 설치 절차와 앱이 사용하는 환경을 먼저 확인하세요. 앱에 필요한 플러그인을 추가하기 어렵거나 프로젝트 의존성을 직접 관리해야 한다면, 별도의 Python 환경이 더 적합할 수 있습니다. 앱이 켜진다는 사실만으로 플러그인 설치와 연구 작업이 검증된 것은 아닙니다.

대표 이미지로 연구 흐름을 끝까지 검수합니다

플러그인 창이 열리는지만 확인하면 분석 환경을 승인하기에 부족합니다. 실제 프로젝트에서 사용할 수 있는 대표 샘플을 고르고, 이전 환경과 새 환경에서 같은 작업을 수행하세요. 시험 데이터는 연구실의 데이터 이용 규칙에 따라 사용이 허용된 것으로 제한합니다.

검수할 때는 입력 이미지가 정상적으로 읽히는지, 필요한 플러그인 작업이 완료되는지, 주석 또는 분석 단계를 재현할 수 있는지, 결과를 프로젝트에서 요구하는 형식으로 내보낼 수 있는지 확인합니다. napari의 레이어 안내를 참고해 레이어 구성과 표시 상태도 비교할 수 있습니다.

아래 항목은 새 환경을 팀에 적용하기 전에 한 번씩 실행하고 기록하세요.

• [ ] 기존 napari와 플러그인의 이름, 설치 경로, 버전을 저장했습니다.
• [ ] 플러그인 관리자의 Qt6 호환 안내를 확인했거나, 안내가 없어 실기 검수 대상으로 표시했습니다.
• [ ] 격리 환경에서 PyQt6 또는 PySide6가 선택됐는지 확인했습니다.
• [ ] 필수 플러그인이 검색되고, 필요한 창과 조작 기능이 실행되는지 확인했습니다.
• [ ] 허용된 대표 샘플로 이미지 열기부터 결과 내보내기까지 마쳤습니다.
• [ ] 이전 환경과 출력 파일, 레이어 구성, 분석 결과를 비교하고 차이를 기록했습니다.
• [ ] 필수 작업이 막히면 기존 환경으로 돌아갈 방법과 책임자를 정했습니다.

결과가 달라졌다면 먼저 입력 데이터, 플러그인 버전, 실행 순서와 저장 설정을 대조하세요. 차이가 허용 가능한지 여부는 연구 프로젝트의 분석 기준에 따라 정해야 합니다. “앱이 실행됨”이나 “플러그인 창이 열림”만으로 결과가 동일하다고 판정하지 마세요.

결과에 따라 이전 여부를 결정합니다

아래 평가는 조직 내부에서 쓸 수 있는 간단한 점수 기준입니다. 각 항목을 0점(실패), 1점(조건부 통과), 2점(통과)으로 기록하세요. 이는 호환성을 보장하는 외부 표준 점수가 아니며, 필수 항목 하나가 실패하면 총점과 관계없이 기존 환경 유지나 업그레이드 보류를 우선 검토해야 합니다.

판정은 점수보다 실패 항목의 중요도로 내립니다. 필수 플러그인과 분석 결과가 요구 조건에 맞으면 팀 이전을 검토합니다. 필수 흐름은 되지만 보조 기능이 빠졌다면 제한 사항과 대체 절차를 문서화합니다. 필수 플러그인이 Qt5에 묶여 작동하지 않으면 기존 환경을 유지하거나 관리자의 호환 업데이트를 기다리세요.

실제 맥이 없다면 원격 환경도 먼저 검수 대상으로 삼으세요

연구실의 Linux 또는 Windows 장비만으로는 macOS에서의 플러그인 실행과 데스크톱 조작을 그대로 확인하기 어렵습니다. 특히 Qt 창 상호작용, 플러그인 표시, 내보내기 같은 작업은 실제 macOS 세션에서 확인해야 합니다. 반대로 데이터 접근 권한이나 장시간의 안정적인 작업, 외부 장비 연결이 필수라면 원격 환경이 요구 조건을 충족하는지 먼저 확인해야 합니다.

맥이 준비되지 않았다면 원격 맥 사용 시작 안내와 연구 작업의 원격 환경 적용 사례를 살펴보고, 필요한 플러그인 설치 권한과 데이터 반입·반출 방식이 맞는지 검토하세요. 연구 데이터의 민감도와 기관 정책도 환경 선택 전에 확인해야 합니다.

현재의 Linux·Windows 환경은 비용을 추가하지 않고 기존 계산 자원을 쓸 수 있지만, macOS 전용 데스크톱 동작을 직접 확인할 수 없고 Qt 백엔드 차이를 해결해 주지 않으며, 별도 장비를 구입하면 예산과 유지 관리 부담이 생깁니다. 반면 원격 맥은 실제 macOS에서 검수할 선택지가 될 수 있지만, 네트워크를 통한 조작과 데이터 이동이 연구 절차에 맞는지 확인해야 합니다. 그런 조건이 맞는다면 CDNMac의 이용 플랜과 사용 조건을 확인한 뒤, 필수 플러그인과 대표 이미지로 먼저 검수해 보세요. 안정적인 장기 계산이나 물리 장비 연결이 핵심이라면 기존 연구실 장비나 전용 장비를 유지하는 편이 더 적절할 수 있습니다.