Project:Python/Namespace packages

This page attempts to shortly describe what namespace packages are, how they work and how to solve the problems caused by them.

Regular packages vs namespace packages
Regular Python packages are structured hierarchically. A subpackage foo.bar needs to be located inside the parent package foo, which also needs to be a valid Python package (i.e. contain at least . The subpackage search is done relatively to the first parent package found in sys.path. That is, if two packages foo.bar and foo.baz are installed in different locations, they both need to install separate instances of the foo package, and the Python interpreter will be able to only load the one of them that is earlier in sys.path.

This can become a problem if two split Gentoo packages install subpackages of the same same parent package. In this case, the build directory (used e.g. by tests) will cover the system parent package, and will make it impossible to load other subpackages.

The Python developers attempt to solve the problem by introducing namespace packages. Unlike regular packages, namespace packages allow the subpackages to be split across different locations. In this case, their parent packages serve as a kind of proxy — when loaded, they do not represent pure regular packages, e.g.:

With a namespace package foo, even if foo.bar and foo.baz are installed in different directories across sys.path, the Python interpreter will be able to locate and load both subpackages correctly.

Implementation of namespace packages
There are currently multiple implementations of namespace packages.

Python 3.5 and newer implement implicit namespaces by PEP-0420. An implicit namespace is created when the parent package is not a valid Python package (i.e. does not have . Unlike before this PEP, such packages are considered valid and namespace search is performed when they are used.

Namespace support for the older Python interpreters is provided via the pkgutil standard library module. In this case, special namespace support code is included in the parent package's that alters package search when the parent package is (implicitly) loaded.

Setuptools also provide their own wrapper for namespace packages.