I think this is actually two distinct problems, one documentation one (which should be addressed in the online docs for all currently maintained versions), and one actual functional issue.

The documentation issue is the one you've reported: in order for the recursive descent to work in walk_packages given the current algorithm, then the combination of the given prefix, and the current global import configuration must allow that package to actually be imported. While there is a note about that limitation, it's currently thoroughly unclear.

The functional issue is two-fold:

1. pkgutil.iter_modules() doesn't identify PEP 420 namespace packages correctly (it ignores them as not being potential packages)

2. The recursive import to check pkg.__path__ uses a name based global __import__ rather than the more state independent https://docs.python.org/3/library/importlib.html#importing-a-source-file-directly technique

It's that second problem that introduces the "prefix must be set to get useful output" behaviour that you're currently seeing.