Home Assistant: No module named 'pkg_resources' (tested fix)

Home Assistant Core 2023.8.x and older import pkg_resources, so on setuptools 82 or newer even hass --version fails with ModuleNotFoundError: No module named 'pkg_resources', and on setuptools 81 it prints pkg_resources is deprecated as an API. Tested fixes: upgrade to 2023.9+, or pin setuptools<81.

1. The error: Home Assistant 2023.8.4 with setuptools 84

A Home Assistant Core venv install (Python 3.11.17) with setuptools 84.2.1. Even hass --version fails, before any config is read:

$ hass --version
Traceback (most recent call last):
  File "/path/to/venv/bin/hass", line 10, in <module>
    sys.exit(main())
             ^^^^^^
  File "/path/to/venv/lib/python3.11/site-packages/homeassistant/__main__.py", line 181, in main
    args = get_arguments()
           ^^^^^^^^^^^^^^^
  File "/path/to/venv/lib/python3.11/site-packages/homeassistant/__main__.py", line 81, in get_arguments
    from . import config as config_util
  File "/path/to/venv/lib/python3.11/site-packages/homeassistant/config.py", line 20, in <module>
    from . import auth
  File "/path/to/venv/lib/python3.11/site-packages/homeassistant/auth/__init__.py", line 19, in <module>
    from .mfa_modules import MultiFactorAuthModule, auth_mfa_module_from_config
  File "/path/to/venv/lib/python3.11/site-packages/homeassistant/auth/mfa_modules/__init__.py", line 12, in <module>
    from homeassistant import data_entry_flow, requirements
  File "/path/to/venv/lib/python3.11/site-packages/homeassistant/requirements.py", line 10, in <module>
    import pkg_resources
ModuleNotFoundError: No module named 'pkg_resources'

homeassistant/requirements.py and homeassistant/util/package.py do a plain import pkg_resources at the top in every release up to 2023.8.x. setuptools 82.0.0 removed pkg_resources. Home Assistant does not declare setuptools as a dependency, so a venv with no setuptools at all fails the same way.

2. On setuptools 81 or older it is only a warning

Same install with setuptools 80.10.2 (81.0.0 printed the same warning):

$ hass --version
/path/to/venv/lib/python3.11/site-packages/homeassistant/requirements.py:10: 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
2023.8.4

That is the pkg_resources is deprecated as an API warning. It is harmless today, but it turns into the error above as soon as setuptools is upgraded to 82 or newer.

3. Fix: upgrade Home Assistant to 2023.9 or newer (tested)

2023.9.0 dropped the pkg_resources imports. Fresh venv, Home Assistant 2023.9.3, setuptools 84.2.1:

$ pip install homeassistant==2023.9.3
$ hass --version
2023.9.3

Newer Home Assistant releases need newer Python (2023.9 still runs on 3.11), so check the Python version of your venv before jumping far ahead.

4. Or keep 2023.8 and pin setuptools below 81

$ pip install "setuptools<81"    # gave 80.10.2
$ PYTHONWARNINGS="ignore:pkg_resources is deprecated as an API" hass --version
2023.8.4

Without PYTHONWARNINGS it runs but prints the warning from section 2. Keep the pin in whatever upgrades the venv, or the next pip install -U setuptools breaks hass again.

Related: No module named 'pkg_resources' (general fix) · the deprecation warning · docker build.

Written with AI assistance. Measured on 2026-10-24 on Linux with Home Assistant Core 2023.8.4 and 2023.9.3, CPython 3.11.17, setuptools 80.10.2, 81.0.0 and 84.2.1. Output pasted unedited except shortened paths. PlainTables is our extension; Home Assistant is free.