mypy --namespace-packages: PEP 420 Imports
mypy --namespace-packages lets mypy resolve PEP 420 implicit namespace packages that have no __init__.py.
Modern src layouts often skip __init__.py. Without this flag mypy can misresolve those modules, so enabling it (often with --explicit-package-bases) is common.
What it does
mypy --namespace-packages makes mypy treat directories without __init__.py as PEP 420 namespace packages when resolving imports. As of recent mypy this behavior is the default, but the flag remains for older versions and the config key still applies.
Common usage
mypy --namespace-packages src/
# the usual pairing for src layouts
mypy --namespace-packages --explicit-package-bases src/Options
| Flag or key | What it does |
|---|---|
| --namespace-packages | Resolve PEP 420 packages without __init__.py |
| namespace_packages | Config key form (true/false) |
| --explicit-package-bases | Common pairing to fix the module base path |
| --no-namespace-packages | Disable, requiring __init__.py everywhere |
In CI
A src/ layout with no __init__.py files frequently needs both --namespace-packages and --explicit-package-bases plus MYPYPATH=src so mypy computes the right fully-qualified module names. Set them in config so CI and local runs agree.
Common errors in CI
Without this you may see "Source file found twice under different module names" or imports resolving to the wrong package. The two-files-one-module error usually means mypy is guessing the package base; add --explicit-package-bases and set MYPYPATH so the base is unambiguous.