See this comment which points to some good resources for namespace packages. In particular, the sample-namespace-packages project has a table that’s been meticulously constructed to show the compatibility options.
There are many factors at play. I’ve found that even that table is inadequate to capture all of the nuances. For example, it focuses primarily on installing the namespace package to a single directory on the sys.path
. If some packages are installed to separate directories, all bets are off. Also, the results depend on how the packages are installed. If installed by pip, the behaviors are pretty well documented, but your mileage may vary if using another installer (especially a deprecated one or a bespoke one; uv
is probably okay).
One nice thing about pip is it will omit the __init__.py
file for pkg_resources
-declared namespaces, allowing pkgutil
-style packages to co-exist (in some cases).
According to that table, packages with different modes may be able to co-exist as long as you’re not using editable installs. It’s also conceivable that modern editable installs are more robust than legacy ones.
The way I did the migration for jaraco
packages, I first migrated from pkg_resources
to pkgutil
in 2019 (jaraco.functools) and then two years later made the transition to native namespace packages, after dropping support for Python 2.
I had very little issue with this approach, as I performed the change on all jaraco.*
projects at once, and I don’t recall any issues, but that’s also probably because these projects have modest adoption and where possible, I encouraged to use the latest version (not pin dependencies).
So you may have better luck with a transitional approach, first from pkg_resources to pkgutil then to native namespace packages. If I were you, I’d try to migrate to native namespace packages first with one package and see how it goes and what breaks.
I hope this helps.