mypy Duplicate module named (tested)

mypy says Duplicate module named "utils" when two files map to the same module name, typically two utils.py in directories without __init__.py. Add __init__.py to the directories, run with --explicit-package-bases, or --exclude one copy.

1. Duplicate module named: two files with the same name

Layout: main.py, pkg_a/utils.py, pkg_b/utils.py, with no __init__.py files. Output (mypy 2.4.0, Python 3.13.5, --no-incremental):

$ tree: main.py pkg_a/utils.py pkg_b/utils.py  (no __init__.py)
$ mypy .
pkg_b/utils.py: error: Duplicate module named "utils" (also at "./pkg_a/utils.py")
pkg_b/utils.py: note: See https://mypy.readthedocs.io/en/stable/running_mypy.html#mapping-file-paths-to-modules for more info
pkg_b/utils.py: note: Common resolutions include:
pkg_b/utils.py: note:     a) using `--exclude` to avoid checking one of them,
pkg_b/utils.py: note:     b) adding `__init__.py` somewhere,
pkg_b/utils.py: note:     c) using `--explicit-package-bases` or adjusting `MYPYPATH`
Found 1 error in 1 file (errors prevented further checking)

$ touch pkg_a/__init__.py pkg_b/__init__.py && mypy .
Success: no issues found in 5 source files

$ mypy --explicit-package-bases .
Success: no issues found in 3 source files

$ mypy --exclude pkg_b .
Success: no issues found in 2 source files

• Without __init__.py, mypy maps each file to a module by its bare name, so both files become utils and mypy stops: "errors prevented further checking".
• Adding __init__.py to both directories makes them pkg_a.utils and pkg_b.utils: fixed (5 source files, the two __init__.py included).
• --explicit-package-bases maps paths relative to the current directory (or MYPYPATH) instead, so no __init__.py is needed.
• --exclude pkg_b works when one copy should not be checked at all (e.g. a vendored or build directory).

2. Source file found twice under different module names

The related error in a src/ layout (src/app/__init__.py, src/app/helpers.py, src/app/core.py), when code imports the same module two ways:

$ cat src/app/core.py
from src.app.helpers import h
from app.helpers import h as h2
$ mypy src
src/app/helpers.py: error: Source file found twice under different module names: "app.helpers" and "src.app.helpers"
src/app/helpers.py: note: See https://mypy.readthedocs.io/en/stable/running_mypy.html#mapping-file-paths-to-modules for more info
src/app/helpers.py: note: Common resolutions include:
src/app/helpers.py: note:     a) adding `__init__.py` somewhere,
src/app/helpers.py: note:     b) using `--explicit-package-bases` or adjusting `MYPYPATH`
Found 1 error in 1 file (errors prevented further checking)

$ cat src/app/core.py   # one import style only
from app.helpers import h
$ mypy src
Success: no issues found in 3 source files

from src.app.helpers and from app.helpers name the same file twice. Use one import style (app.…, with src as the source root) and the error is gone.

In pyproject.toml the flags are [tool.mypy] explicit_package_bases = true and exclude = ["pkg_b/"].

Written with AI assistance. Measured on 2026-10-23 with mypy 2.4.0 and Python 3.13.5 on Linux. Commands ran verbatim and the output was pasted unedited. PlainTables is our extension; mypy is free.