No module named 'pkg_resources' in ComfyUI: Fix setuptools

If ComfyUI shows ModuleNotFoundError: No module named 'pkg_resources', the failing custom node is usually using an old setuptools runtime API.

This is different from a missing model file or a normal optional backend warning. pkg_resources sits in the Python packaging layer, so a broken or incompatible setuptools baseline can affect more than one plugin.

Telemetry snapshot queried on April 17, 2026: 92 events across 9 installs for comfyui_fatal_error_detected.

Quick Answer

What the Log Looks Like

Typical log lines:

ModuleNotFoundError: No module named 'pkg_resources'

or:

IMPORT FAILED: ComfyUI-SomePlugin
from pkg_resources import get_distribution
ModuleNotFoundError: No module named 'pkg_resources'

or:

Cannot import custom nodes:
No module named 'pkg_resources'

Why This Happens

pkg_resources used to be provided by setuptools and was commonly used for package metadata, entry points, and resource loading.

The setuptools project now treats pkg_resources as deprecated historical API. Its official documentation says it has long been discouraged, issued deprecation warnings as early as setuptools v67.5.0, and is no longer included in current setuptools distributions as of v82.0.0.

In one GitHub Windows portable package test, setuptools 81.0.0 still imported pkg_resources, but it printed a warning that projects relying on this API should pin below setuptools 81. This was a compatibility signal, not a path or Python-version requirement. That is why the repair below uses setuptools<81, not just <82.

That means a blind pip install --upgrade setuptools can make an old ComfyUI plugin worse if the plugin still imports pkg_resources. For users, the practical repair is to put a compatible setuptools version back into the exact Python environment that starts ComfyUI.

Step 1: Confirm the Python Environment

Most failed repairs happen because the command ran in system Python while ComfyUI uses embedded Python or a virtual environment.

For the GitHub Windows portable package, run this from the extracted portable root: the folder that contains the run_*.bat files, python_embeded, and ComfyUI.

Do not run it from inside the ComfyUI\ subfolder. In the standard portable layout, python_embeded is next to ComfyUI, not inside it.

.\python_embeded\python.exe -s -c "import sys; print(sys.executable); print(sys.version)"
.\python_embeded\python.exe -s -m pip show setuptools

For a manual install or venv:

python -c "import sys; print(sys.executable); print(sys.version)"
python -m pip show setuptools

If the path is not the Python that starts ComfyUI, stop and switch environments before installing anything.

For ComfyUI Desktop or another managed launcher, use the app's terminal or environment controls instead of copying the portable python_embeded path.

Step 2: Install a Compatible setuptools Baseline

For the GitHub Windows portable package:

.\python_embeded\python.exe -s -m pip install --upgrade wheel "setuptools<81"

For a manual venv:

python -m pip install --upgrade wheel "setuptools<81"

Then verify the import in the same environment:

.\python_embeded\python.exe -s -c "import pkg_resources; import setuptools; print(setuptools.__version__)"

Manual venv:

python -c "import pkg_resources; import setuptools; print(setuptools.__version__)"

If the command prints a setuptools version and does not throw an import error, restart ComfyUI and retest the plugin that failed.

If you also decide to upgrade pip, verify it still runs before restarting ComfyUI:

.\python_embeded\python.exe -s -m pip --version

Step 3: Run a Narrow Health Check

After restarting ComfyUI, check whether the repair created dependency conflicts:

python -m pip check

For the GitHub Windows portable package:

.\python_embeded\python.exe -s -m pip check

If pip check reports conflicts around core packages such as torch, numpy, opencv-python, pillow, or transformers, do not keep installing unrelated packages. Move to ComfyUI Dependency Conflicts.

Step 4: If pip Itself Is Broken

If python -m pip cannot run, the environment is more damaged than a missing plugin dependency.

At that point, the safer choices are:

• restore the environment from a known-good backup
• rebuild the Python environment while preserving models and workflows
• use Wonderful Launcher to take over the install and collect the startup log before more package mutations

Avoid copying pkg_resources files by hand between Python installs. That can create a package metadata mismatch that fails later in harder-to-debug ways.

What Not To Do

• Do not install setuptools into system Python and expect ComfyUI portable to see it.
• Do not use pip install -U setuptools without the <81 cap for this specific error.
• Do not delete and recreate ComfyUI before confirming the exact Python path.
• Do not run every plugin's requirements.txt just because one plugin imports pkg_resources.
• Do not treat this as a model download problem; it is a Python packaging/runtime import problem.

When It Is Safe To Ignore

This error is rarely worth ignoring if the affected plugin is needed. However, you can defer it when:

• ComfyUI opens normally
• the failed plugin is not used by your workflow
• only one optional custom node family is affected

For the broader decision process, see ComfyUI No Module Named Error: When It Is Safe to Ignore.

Related Guides

• ComfyUI No Module Named Error: When It Is Safe to Ignore
• How to Fix ComfyUI Plugin Import Failed Errors
• ComfyUI Dependency Conflicts
• OpenCV cv2 Missing in ComfyUI
• ONNX / ONNXRuntime Missing in ComfyUI

Source References

• setuptools documentation: Package Discovery and Resource Access using pkg_resources