エラー解決

【ComfyUI】カスタムノードが読み込まれない時の原因と解決策7選

· 13分で読めます

問題の概要：ComfyUIでカスタムノードが表示されない・読み込まれない

ComfyUIは、その柔軟性から多くのユーザーがカスタムノード（Custom Nodes）をインストールして機能を拡張します。しかし、インストールしたカスタムノードがワークフローに表示されなかったり、起動時にエラーが発生したりする問題は非常に頻繁に発生します。この問題は、初心者から中級者まで多くのユーザーを悩ませる典型的なトラブルです。

具体的には、以下のような症状が現れます：

  • カスタムノードをインストールしたのに、ノード一覧（右クリックメニュー）に表示されない
  • ComfyUI起動時にターミナル/コンソールにエラーメッセージが表示される（例: ModuleNotFoundError: No module named 'custom_node_module'）
  • ワークフローを読み込むと「Missing Nodes」と表示され、カスタムノード部分が赤くなる
  • ノードは表示されるが、実行時にエラーが発生する

これらの問題は、環境設定、依存関係、ノードの互換性など、様々な要因によって引き起こされます。

原因の解説：なぜカスタムノードは読み込まれなくなるのか？

カスタムノードが読み込まれない主な原因は、以下の5つに大別できます。

1. 依存関係の不足

ほとんどのカスタムノードは、PyTorchやOpenCV、その他のPythonライブラリに依存しています。requirements.txt や install.py に記載された依存パッケージが正しくインストールされていないと、ノードの読み込みに失敗します。

2. インストールパスの誤り

ComfyUIは、カスタムノードを特定のディレクトリ（custom_nodes/）から読み込みます。Gitクローンやファイルの配置を間違えると、ComfyUIがノードの存在を認識できません。

3. Pythonパスや環境の問題

システムに複数のPython環境がある場合、ComfyUIが使用しているPython環境と、ノードをインストールした環境が異なっている可能性があります。特に、venvやconda環境を使用している場合に発生しやすい問題です。

4. ComfyUI本体とのバージョン互換性

カスタムノードは、特定のバージョンのComfyUI APIを前提として開発されています。ComfyUI本体をアップデートした後、古いカスタムノードが互換性を失い、読み込まれなくなることがあります。その逆もあり得ます。

5. ノードファイルの構造や構文エラー

__init__.py ファイルの欠落、Python構文エラー、または必須クラス（NODE_CLASS_MAPPINGS）のエクスポート漏れがあると、ノードとして認識されません。

解決方法：ステップバイステップで問題を切り分ける

以下の手順を順番に試し、問題を解決してください。

ステップ1：ComfyUIの起動ログを確認する

まず、問題の具体的なエラーメッセージを取得します。ターミナルやコマンドプロンプトでComfyUIを起動し、出力されるログを仔細に確認してください。エラーメッセージは解決の最大の手がかりです。

# ComfyUIの起動例（Windows）
cd C:ComfyUI_windows_portable
python main.py

# エラーメッセージの例
# ERROR:    Could not import custom node module "ComfyUI-Custom-Scripts" due to: No module named 'skimage'

ステップ2：依存関係をインストールする

ログに ModuleNotFoundError が表示された場合、そのモジュールを手動でインストールします。カスタムノードのディレクトリ内に requirements.txt があれば、それを利用します。

# カスタムノードのディレクトリに移動
cd ComfyUI/custom_nodes/your_custom_node_name

# requirements.txtからインストール（ComfyUIが使用するPythonで実行）
pip install -r requirements.txt

# 単一のパッケージをインストールする場合（例: scikit-image）
pip install scikit-image

重要: pipを実行する際は、ComfyUIが実際に使用しているPython環境を必ず確認してください。多くのトラブルの原因はここにあります。ComfyUIの起動ログの最初の方に Python path: という行があるので、それを確認します。

ステップ3：インストールパスを確認する

カスタムノードが正しい場所に配置されているか確認します。ComfyUIのルートディレクトリ直下の custom_nodes フォルダ内に、ノードのフォルダがそのまま配置されている必要があります。

正しい構造例：
ComfyUI/
├── custom_nodes/
│   ├── ComfyUI-Manager/  # カスタムノードのフォルダ
│   │   ├── __init__.py
│   │   ├── nodes.py
│   │   └── ...
│   └── another-node/
├── web/
├── models/
└── main.py

誤った構造例：
ComfyUI/
├── custom_nodes/
│   └── some-subfolder/  # 余計な階層
│       └── ComfyUI-Manager/

ステップ4：ComfyUIのキャッシュを削除する

ノード情報はキャッシュされることがあります。古いキャッシュが残っていると、新しくインストールしたノードが認識されません。以下のファイルを削除またはリネームしてから、ComfyUIを再起動します。

# キャッシュファイルの場所（例）
# Windows: ComfyUIweb__pycache__  (ディレクトリごと削除可)
# ComfyUIcustom_nodes__pycache__

# または、ComfyUI Managerをインストールしている場合は、その機能を使う
# "Manager"メニュー → "Clear Cache (Custom Nodes)" を実行

ステップ5：ノードの互換性を確認する

ComfyUI本体を更新した直後に問題が発生した場合は、バージョン互換性を疑います。カスタムノードのGitHubページやDiscordチャンネルで、使用しているComfyUIのバージョンに対応しているか確認してください。必要に応じて、ノードを特定のコミットにロールバックします。

# カスタムノードを特定のバージョン（コミット）に戻す例
cd ComfyUI/custom_nodes/your_problematic_node
git log --oneline -5  # 最近のコミットを確認
git checkout a1b2c3d4  # 安定していると思われるコミットハッシュに切り替え

ステップ6：最小構成でテストする

他のカスタムノードとの衝突を疑います。custom_nodes フォルダ内の他のノードをすべて別の場所に退避させ、問題のノード1つのみの状態でComfyUIを起動します。これで読み込まれるなら、他のノードとの競合が原因です。

ステップ7：ComfyUI Managerを活用する

カスタムノードの管理が難しいと感じたら、ComfyUI Manager 自体をインストールすることを強くお勧めします。Managerは、ノードのインストール、更新、依存関係の解決をGUIから簡単に行えるだけでなく、ノードの互換性チェック機能も備えています。

# ComfyUI Managerのインストール（手動）
cd ComfyUI/custom_nodes
git clone https://github.com/ltdrdata/ComfyUI-Manager.git
cd ComfyUI-Manager
pip install -r requirements.txt

インストール後、ComfyUIを再起動すると、”Manager”メニューが追加されます。ここから多くのカスタムノードをワンクリックでインストールできるようになります。

コード例：シンプルなカスタムノードの構造

カスタムノードがどのように構成されているかを理解することは、トラブルシューティングに役立ちます。以下は最小限のカスタムノードの例です。

# custom_nodes/my_custom_node/__init__.py
# このファイルが存在し、以下のようにマッピングをエクスポートすることが必須

from .nodes import MyCustomNode

NODE_CLASS_MAPPINGS = {
    "My Custom Node": MyCustomNode
}

NODE_DISPLAY_NAME_MAPPINGS = {
    "My Custom Node": "My Custom Node"
}

# custom_nodes/my_custom_node/nodes.py
import torch

class MyCustomNode:
    @classmethod
    def INPUT_TYPES(cls):
        return {
            "required": {
                "image": ("IMAGE",),
                "multiplier": ("FLOAT", {"default": 1.0, "min": 0.0, "max": 10.0})
            },
        }

    RETURN_TYPES = ("IMAGE",)
    FUNCTION = "process_image"
    CATEGORY = "image/processing"

    def process_image(self, image, multiplier):
        # 簡単な処理例：画像を乗算する
        result = image * multiplier
        return (result,)

もしあなたがノード開発者で、自分のノードが読み込まれない場合は、__init__.py ファイルが存在し、NODE_CLASS_MAPPINGS が正しくエクスポートされているか、nodes.py に構文エラーがないかを最初に確認してください。

まとめ・補足情報

ComfyUIのカスタムノードが読み込まれない問題は、一見複雑ですが、体系的なアプローチでほとんどが解決できます。最も重要なのは、起動ログのエラーメッセージを読むことです。エラーメッセージは、依存関係の欠落、パスエラー、構文エラーなど、問題の核心を直接教えてくれます。

また、環境管理を徹底することも有効です。venvやDockerなどの仮想環境を使用して、ComfyUI用のPython環境を分離しておくことで、システムのPython環境との衝突を防ぐことができます。

最後に、ComfyUIは開発が活発でアップデートが頻繁なため、公式のDiscordサーバーや各カスタムノードのGitHub Issueページは、最新のトラブルシューティング情報の宝庫です。同じ問題に遭遇した他のユーザーの解決策が見つかる可能性が非常に高いです。焦らず、一つ一つの可能性を潰していく姿勢が、ComfyUIを使いこなすための近道となります。

この記事は役に立ちましたか？