supervisord: No module named 'pkg_resources' (tested fix)

supervisor 4.2.5 and older do import pkg_resources in supervisor/options.py, so on setuptools 82 or newer supervisord and supervisorctl fail with ModuleNotFoundError: No module named 'pkg_resources'. Tested fix: pip install supervisor==4.3.0.

1. The error: supervisor 4.2.5 with setuptools 84

pip install supervisor==4.2.5 (2022-12-24) into a Python 3.11.17 venv with setuptools 84.2.1:

$ supervisord --version
Traceback (most recent call last):
  File "/path/to/venv/bin/supervisord", line 4, in <module>
    from supervisor.supervisord import main
  File "/path/to/venv/lib/python3.11/site-packages/supervisor/supervisord.py", line 41, in <module>
    from supervisor.options import ServerOptions
  File "/path/to/venv/lib/python3.11/site-packages/supervisor/options.py", line 13, in <module>
    import pkg_resources
ModuleNotFoundError: No module named 'pkg_resources'

supervisorctl fails the same way. supervisor/options.py line 13 is a plain import pkg_resources, and setuptools 82.0.0 removed that module. This hits venvs, Docker images and pip install --user setups where setuptools got upgraded after supervisor was installed.

2. Fix: upgrade supervisor to 4.3.0 (tested)

$ pip install supervisor==4.3.0
$ supervisord --version
4.3.0

Same venv, still setuptools 84.2.1. 4.3.0 (2025-08-23) loads its package data with importlib on Python 3.8 and newer instead of pkg_resources (see the comment in supervisor/compat.py). Your supervisord.conf does not need changes for this.

3. Or stay on 4.2.5 and pin setuptools below 81

$ pip install "setuptools<81"    # gave 80.10.2
$ supervisord --version
/path/to/venv/lib/python3.11/site-packages/supervisor/options.py:13: UserWarning: pkg_resources is deprecated as an API. See https://setuptools.pypa.io/en/latest/pkg_resources.html. The pkg_resources package is slated for removal as early as 2025-11-30. Refrain from using this package or pin to Setuptools<81.
  import pkg_resources
4.2.5

It runs, with the pkg_resources is deprecated as an API warning. To hide it, set the variable in the environment that starts supervisord (systemd unit, Dockerfile ENV, or shell):

$ PYTHONWARNINGS="ignore:pkg_resources is deprecated as an API" supervisord --version
4.2.5

Related: No module named 'pkg_resources' (general fix) · docker build · Trac 1.6.

Written with AI assistance. Measured on 2026-10-24 on Linux with supervisor 4.2.5 and 4.3.0, CPython 3.11.17, setuptools 80.10.2 and 84.2.1. Output pasted unedited except shortened paths. PlainTables is our extension; supervisor is free.