Skip to content

Troubleshooting Common Issues JP

Jump to bottom
Hiromichi Yokoyama edited this page Aug 4, 2026 · 2 revisions

よくある問題のトラブルシューティング

このページは、MoleditPy の実際のソースコード、またはこの wiki の他のページで裏付けられる問題のみを扱います。誰も報告していない症状について推測することはあえてしていません。

1. 初回起動が遅い

これは想定内の挙動で、自然に解消します。アプリ自身の README/Home ページによれば、インストール直後（またはアップグレード直後）の最初の起動は、以降の起動よりも明らかに時間がかかることがよくあり、理由は独立した 2 つです：

  1. Matplotlib がフォントキャッシュを構築する。 マシン上で Matplotlib（NMR/MS/スペクトルアナライザーなど複数のプラグインで使用）が初めて動作するとき、インストール済みフォントをスキャンしてキャッシュを書き込みます。それに関するコンソールメッセージが表示されることがあります。これは一度だけ発生します。
  2. Python が大きなライブラリの .pyc バイトコードキャッシュをコンパイルする — RDKit、PyVista/VTK、（Windows/macOS では）OpenBabel について、インストール後や Python バージョン変更後に各ライブラリが最初にインポートされる際に発生します。moleditpy-linux の依存関係スタックはより小さいですが（下記§4参照）、これも一般的には無縁ではありません。

毎回の起動が遅いままの場合（初回だけでなく）はこの問題ではありません — その場合は §3 の OpenGL/VTK 関連の遅延/失敗を参照してください。

2. Qt プラットフォームプラグインのエラー（「Qt platform plugin をロードできない」、ヘッドレス/SSH/CI）

ディスプレイの接続されていない SSH セッション、コンテナ、CI ランナー上で moleditpy を実行すると、Qt の既定のプラットフォームバックエンド（Linux では xcb）が初期化できず、PyQt6 は Qt platform plugin に関するエラーで起動に失敗します。以下を設定してください：

export QT_QPA_PLATFORM=offscreen
moleditpy

QT_QPA_PLATFORM は MoleditPy 自身のコードでは一切読み取られていません — moleditpy の Python コードが動く前に Qt 自体が消費する環境変数であり、CLI フラグではなく環境変数として設定しなければならない理由もそこにあります。これが MOLEDITPY_HEADLESS=1（自動実行がクリックを待って止まらないよう、MoleditPy 自身のブロッキングなエラー/警告ダイアログも追加で抑制します）とどう組み合わさるかは Command-Line Options を参照してください。これはメイン app の CLAUDE.md にある通り、MoleditPy 自身のテストスイートがヘッドレス実行に使っている組み合わせそのものです（MOLEDITPY_HEADLESS=1 QT_QPA_PLATFORM=offscreen python tests/run_all_tests.py ...）。

QT_QPA_PLATFORM=offscreen は、表示されるウィンドウが一切ない 完全にヘッドレスなプロセスになる点に注意してください — これは自動化/テスト用であり、通常のデスクトップセッションで「ウィンドウが表示されない」問題の解決策ではありません（それについては §3 を参照）。

3. 3D ビューが表示されない、真っ黒/空白になる、起動時にクラッシュする（OpenGL/VTK）

MoleditPy の 3D パネルは CustomQtInteractor（pyvistaqt/VTK ウィジェット）で、MainWindow の初期化パス（ui/main_window_init.py: _init_right_panel）内で直接構築されており、その構築を囲む try/except はありません — 基盤となる OpenGL コンテキストや VTK のレンダリングバックエンドが初期化できない場合（典型的には：GPU ドライバがない、適切な GL サポートのないヘッドレス/リモートデスクトップセッション、Linux 上で壊れた Mesa/グラフィックドライバのインストールなど）、アプリ内での丁寧なエラーメッセージではなく、ターミナルに VTK/OpenGL のトレースバックが表示される即時クラッシュとして現れます。

確認すべき点：

  • Linux では、Mesa/OpenGL のユーザースペースドライバがインストールされていること（ディストロに応じた libgl1-mesa-dev 等）、GPU/ソフトウェアレンダリングの経路がまったくない環境で実行しようとしていないことを確認してください。リモートセッション（VNC/RDP/X 転送）は適切な GLX サポートを欠くことがあります — ローカルセッションが最も信頼できる環境です。
  • これは QT_QPA_PLATFORM=offscreen（§2）とは別問題です — offscreen モードにはそもそも画面上のウィンドウがないため、このクラスの問題を完全に回避します（クラッシュがグラフィック関連かどうかを確認するのに便利です：offscreen で問題なく起動するなら、問題は MoleditPy ではなくディスプレイ/OpenGL の設定に固有のものです）。
  • 特定の 高度な 3D 表示スタイル/エフェクト（PBR、SSAO、EDL、Depth Peeling — 公式の Advanced Rendering/Cube File Viewer Advanced プラグインが追加するもの）でのみクラッシュする場合は、まず組み込みのスタイル（Ball & Stick、CPK、Wireframe、Stick）に切り替えて、問題が基本の VTK パイプラインにあるのかそれらのエフェクトにあるのかを切り分けてください。

4. Linux：OpenBabel が無効になっている、「3D 変換」のフォールバックが起きない

Linux では moleditpy-linux（プレーンな moleditpy ではない — pip install moleditpy-installer はプラットフォームに応じて正しい方を自動選択します）をインストールしてください。このディストリビューションでは、OpenBabel サポートがハードコードで無効化されています：moleditpy_linux/__init__.py は OBABEL_AVAILABLE = False を無条件に設定します（検出ではなく、常に無効）。これは、OpenBabel にバンドルされたネイティブライブラリと Linux 依存関係スタックの残りの部分とのライブラリ競合を避けるための意図的な措置です。結果として：

  • 2D から 3D への変換時の RDKit→OpenBabel フォールバックは Linux には存在しません — 与えられた分子で RDKit の埋め込みが失敗しても、自動的な再試行はありません。
  • OpenBabel を特に必要とする 3D 最適化 手法 の選択肢は利用できません。
  • これはこのプラットフォームにおける意図的かつ恒久的なトレードオフであり、バグ報告すべきものではありません — インストールの全体像については Installation for Linux ページを参照してください。

5. プラグインが読み込めない、またはプラグインが起動時にアプリを壊した

Plugin ▸ Plugin Manager... を開き、Status 列を確認してください：

ステータス 意味
Loaded（緑） 正常動作中。
No Entry Point（灰） プラグインファイルに initialize()、run()、autorun() のいずれもない — プラグイン自体の設計上または誤りにより、何も起きていません。
Error (Init): ... / Error (Autorun): ...（赤） 起動時にプラグインの initialize()/autorun() が例外を投げました。メッセージはそのセルにそのまま表示され、完全なトレースバックはログ（コンソール、または有効化していればログファイル — §7 参照）に書き込まれます。
（表に現れない） ファイルがインポート自体に失敗するプラグイン（構文エラー、モジュールレベルで必須のサードパーティパッケージが見つからない、など）は、この表にはまったく現れません — 捕捉されて警告としてログに記録され、静かにスキップされます。プラグインが表示されるはずなのに表示されない場合は、コンソール出力やログファイルで "Failed to load plugin ..." という警告を確認してください。

同じダイアログの Reload Plugins は、再起動せずにすべてを再スキャン・再実行します — プラグインファイルをその場で修正した後に便利です。

プラグインの失敗が深刻で、プラグインマネージャーに到達する前に MoleditPy 自体がクラッシュしてしまう場合は、以下で起動してください：

moleditpy --safe

これによりすべてのプラグインの読み込みがスキップされ（プラグインファイルは1つも読み取られません）、動作するアプリに戻ることができます。問題のプラグインを ~/.moleditpy/plugins/ から削除/調査し（動作するセッションに到達できるなら Open Plugin Folder 経由でも可）、通常どおり再起動してください。セーフモードの詳細は Using Plugins と Command-Line Options を参照してください。

6. Plugin Installer：バージョン/OS/依存関係の不一致

Plugin Installer プラグイン経由でプラグインがグレーアウトしていたりインストールできなかったりする場合、最も可能性が高いのは以下のいずれかです：

  • supported_moleditpy_version — プラグインが宣言するメイン app のバージョン範囲を、インストール済みの MoleditPy が満たしていない。
  • supported_python_version — 同様に、あなたの Python インタプリタについて。
  • supported_os — 一部のプラグインは、バックエンドが実際に動作できる特定の OS に制限されています（例えば PySCF Calculator プラグインは macOS/Linux/WSL のみを挙げています。これは PySCF 自体が Windows へのインストールが不安定であることが文書化されているためです）。
  • Python の依存関係が不足している — Installer は importlib.metadata を通じて各プラグインの宣言済み依存関係を確認し、プラグインの ファイル 自体は正常にインストールされても、実際に機能する前に自分で実行すべき「Copy install command」（例：pip install pyscf geometric）を提示します。
  • ダウンロードしたファイルとレジストリに記録されたハッシュの SHA-256 不一致 はインストールを完全にブロックします（これはバグではなく意図的な整合性チェックです）— これに遭遇した場合、たいていはダウンロードの破損か、レジストリのローカルコピーが古いことが原因です。もう一度試してみてください。

7. ログファイルの場所（有効化する方法）

既定では、MoleditPy はコンソール（stdout）にのみ INFO レベルでログを出力します。セッションをまたいでログを残すには：

Settings ▸ Settings... ▸ Other タブ：

  • 「Save log to file (~/.moleditpy/moleditpy.log)」 — チェックすると、~/.moleditpy/moleditpy.log にもログが書き込まれます。ローテーションされるログで、1 ファイルあたり 1 MiB を上限に 3 世代のバックアップを保持するため（moleditpy.log、moleditpy.log.1、.2、.3）、無制限には肥大化しません。
  • 「Enable DEBUG level logging」 — ログレベルを INFO からより詳細な DEBUG に引き上げます（バグ報告時に有用です）。

どちらの設定も起動時に一度だけ ~/.moleditpy/settings.json から読み取られます — トグルの変更は 次回 の起動から反映され、即座には反映されません（main.py: _read_startup_log_settings() は GUI や設定ダイアログが存在するより前に実行されます）。

ERROR/CRITICAL レベルのログレコード（sys.excepthook を通る未捕捉の例外を含む）はすべて、非ブロッキングの 「MoleditPy — Error」 ダイアログ（メッセージと Show Details... によるトレースバック付き）をポップアップします。ただし次の場合を除きます：MOLEDITPY_HEADLESS=1 で実行している場合（自動実行が止まらないようダイアログは完全に無効化されます）、同じエラーが直近 10 秒以内に既にダイアログを表示済みの場合（高速に繰り返すエラーでスパムにならないよう重複排除されます）、その瞬間に別のモーダルダイアログが既にアクティブな場合（より具体的なエラーダイアログの上に重ならないよう、汎用ダイアログは静かにしています）。

8. 関連ページ

Clone this wiki locally