Skip to content

Troubleshooting Common Issues JP

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

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

このページは、MoleditPy を日常的に使う中で遭遇しがちな問題 — 起動の遅さ、3D ビューやプラグインの不調、ファイルのインポート/エクスポート失敗 — を扱います。ヘッドレス環境や CI でのデバッグ、ログの有効化については、末尾の上級者向け/診断セクションを参照してください。

初回起動が遅い

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

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

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

3D ビューが表示されない、または起動時にクラッシュする

MoleditPy の 3D パネルは起動時に直接構築され、基盤となる OpenGL コンテキストや VTK のレンダリングバックエンドが初期化できない場合のフォールバックはありません。典型的な原因は、GPU ドライバがない、適切な GL サポートのないヘッドレス/リモートデスクトップセッション、Linux 上で壊れた Mesa/グラフィックドライバのインストールなどです。この場合、アプリ内の丁寧なエラーメッセージではなく、ターミナルに VTK/OpenGL のトレースバックが表示される即時クラッシュとして現れます。

確認すべき点。

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

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

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

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

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

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

moleditpy --safe

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

Plugin Installer がグレーアウトする、またはインストールできない

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

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

ファイルのインポート/エクスポートの問題

症状 想定される原因 対処
.mol/.sdf を開くと MOL Import Error ダイアログが出る ファイルが破損している、手動編集で不正な状態になっている、または実際は MOL/SDF ファイルではない 元のソフトからファイルを再エクスポートする。拡張子が実際の内容と一致しているか確認する
ステータスバーに Invalid SMILES / Invalid InChI と出る 入力した文字列が RDKit の規則でパースできない 文字列を再確認する。これはポップアップではなくステータスバー表示なので見逃しやすい
.pmeprj を開くと 「This file is not a valid PME Project format.」 と出る ファイルが MoleditPy のプロジェクトファイルでない、または "format" マーカーが変更されている 本物の .pmeprj を開いているか確認する。"version" フィールドの不一致は失敗せず警告付きで読み込まれる
.pmeraw ファイルが開けない、または開くのが不安 これはレガシーな Python pickle 形式で、読み込み時に任意のコードを実行し得ます 自分が作成した .pmeraw ファイルのみを開く。他者と共有するものには .pmeprj を使う
.xyz をインポートすると Import XYZ Charge ダイアログが出る 幾何情報だけでは RDKit が電荷 0 で結合を自動決定できなかった 正しい分子全体の電荷を入力するか、Skip chemistry をクリックして距離ベースの結合推定にフォールバックする

MoleditPy が読み書きできる全形式と、各プラグインが追加する形式については File Formats and Import/Export を参照してください。

Linux: 3D 変換が Open Babel にフォールバックしない

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

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

上級者向け/診断

このページの残りの部分は、ヘッドレス環境、CI、ログを使ったデバッグ向けです。ほとんどのユーザーには不要です。

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 を参照してください。

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

ログファイルとデバッグログ

既定では、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 から読み取られます — トグルの変更は次回の起動から反映され、即座には反映されません。

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

関連ページ

Clone this wiki locally