import fs: No module named 'pkg_resources' (PyFilesystem2, tested)

import fs (PyFilesystem2 2.4.16, the latest release) fails with ModuleNotFoundError: No module named 'pkg_resources' at fs/__init__.py line 4. Tested fix: setuptools<81.

1. The error: import fs fails

fs (PyFilesystem2) 2.4.16 is the newest release on PyPI (uploaded 2022-05-02). Its fs/__init__.py calls pkg_resources.declare_namespace at import time, and setuptools 82.0.0 removed pkg_resources. Our test script, b1.py:

import fs
print(fs.__version__)
with fs.open_fs("mem://") as m:
    m.writetext("hello.txt", "hi")
    print(m.listdir("/"), m.readtext("hello.txt"))

With fs 2.4.16 and setuptools 84.2.1 on Python 3.11.17:

$ python b1.py
Traceback (most recent call last):
  File "b1.py", line 1, in <module>
    import fs
  File "/path/to/venv/lib/python3.11/site-packages/fs/__init__.py", line 4, in <module>
    __import__("pkg_resources").declare_namespace(__name__)  # type: ignore
    ^^^^^^^^^^^^^^^^^^^^^^^^^^^
ModuleNotFoundError: No module named 'pkg_resources'

fs depends on setuptools with no version cap. If setuptools is missing, installing fs pulls the newest one, and new venvs often come seeded with a recent setuptools anyway (ours had 84.2.1). Either way the first import fs fails. The same happens with any package that imports fs.

2. Fix: pin setuptools below 81

$ pip install "setuptools<81"        # got 80.10.2
$ python b1.py
/path/to/venv/lib/python3.11/site-packages/fs/__init__.py:4: 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").declare_namespace(__name__)  # type: ignore
2.4.16
['hello.txt'] hi

It works again, with a deprecation UserWarning. Put setuptools<81 in your requirements file or lock file next to fs so the next fresh install doesn't pull the newest setuptools back in. Since there has been no fs release since 2022, this pin is the fix until a new version or a replacement library removes the pkg_resources call.

Same root cause elsewhere: No module named 'pkg_resources' (general fix) · tensorboard · Ansible · docker build.

Written with AI assistance. Measured on 2026-10-24 on Linux with fs 2.4.16, CPython 3.11.17 and setuptools 84.2.1, then 80.10.2. Script and output pasted unedited except shortened paths. PlainTables is our extension; PyFilesystem2 is free.