sphinx autodoc: "failed to import module" error

Fix Sphinx autodoc "failed to import module" errors

TL;DR

Autodoc imports your package to read its docstrings, and it fails when the build environment cannot import it: conf.py does not put the package on sys.path, or a dependency is missing in that environment. Point sys.path at the repo and install the dependencies, then rebuild. The warning disappears because the import autodoc performs now succeeds.

The error

docs/api.rst:4: WARNING: autodoc: failed to import module 'mypackage'; the following exception was raised:
No module named 'mypackage'

Steps

1. Read the exception chain at the end of the warning first; it tells you exactly what failed. Then reproduce outside Sphinx in the build environment: python -c "import mypackage".

Expected: the same ImportError or ModuleNotFoundError the warning shows.

1. In conf.py (usually docs/conf.py), insert the repo root ahead of everything: sys.path.insert(0, os.path.abspath("..")), adjusting the depth so the path lands on the directory that contains your package.

Expected: re-running the import from step 1 now succeeds.

1. If the failure names a third-party dependency instead of your package, install it in the build environment: pip install -r requirements.txt or pip install -e . for the package itself.

Expected: the import from step 1 succeeds with no missing modules.

1. Rebuild: sphinx-build -b html docs docs/_build.

Expected: autodoc renders the module's docstrings and no 'failed to import module' warnings appear.

Use this when

• autodoc warns it cannot import your own package
• the warning's exception chain names a missing third-party dependency
• docs build on Read the Docs while local builds work (different dependency set)

Not for this skill when

• 'duplicate object description' (the module imports fine; it is documented twice)
• 'has no setup()' (extension loading fails before autodoc runs)
• intersphinx inventory warnings (remote docs, not local imports)

Variant phrasings

• sphinx autodoc failed to import module
• autodoc No module named warning
• sphinx WARNING autodoc failed to import
• sphinx autodoc import error conf.py sys.path

Why it happens

Autodoc works by importing the documented modules in the Sphinx process and introspecting them, so it inherits every import requirement your package has. The docs build typically runs from the docs/ directory, which means the package at the repo root is not importable unless conf.py adds it to sys.path. The second classic cause is environment drift: the package's dependencies are installed on your laptop but not in the docs build environment or the Read the Docs container.

Edge cases

• Use an absolute path derived from the conf.py location (os.path.abspath(os.path.join(os.path.dirname(__file__), '..'))) so the build works regardless of the working directory.
• Editable installs (pip install -e .) fix this permanently for local builds and are what most projects do in CI.
• If the import has side effects (network calls, heavy model loads), consider autodocmockimports for the heavy third-party parts instead of installing everything.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_PGCd9B7tRkkW9fAUt2uQxA