sphinx mock_imports not working, autodoc import error persists

Fix autodocmockimports not suppressing autodoc import errors

TL;DR

Mocking only works when the list names top-level packages: autodocmockimports = ['torch'] intercepts 'import torch' and everything under it, but ['torch.nn'] does not. List the top-level names (and confirm autodoc is actually enabled), then rebuild. The import warning clears because the import machinery is intercepted before your code runs.

The error

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

Steps

1. In conf.py, confirm both lines exist: extensions includes sphinx.ext.autodoc, and autodoc_mock_imports is set. Without the extension, the mock setting is silently ignored.

Expected: both are present.

1. Rewrite the list with TOP-LEVEL package names only: autodoc_mock_imports = ["heavylib"], not ["heavylib.submodule"]. Mocking the top level covers every submodule import beneath it.

Expected: the list contains importable top-level names matching the warning's 'No module named' value.

1. Rebuild verbose and check: sphinx-build -v -b html docs docs/_build 2>&1 | grep "failed to import".

Expected: no output: the warning is gone.

Use this when

• autodocmockimports is set but 'failed to import module' persists
• the missing module is a heavy optional dependency (ML frameworks, DB drivers)
• the mock list contains dotted submodule paths

Not for this skill when

• 'has no setup()' (extension loading fails before mocking matters)
• import errors for your own package (fix sys.path; mocking your own code hides real breakage)
• attribute errors inside docstrings (the import worked; the object is wrong)

Variant phrasings

• sphinx autodocmockimports not working
• autodoc mock imports failed to import module persists
• sphinx mock heavy dependencies autodoc
• autodocmockimports submodule not mocked

Why it happens

autodocmockimports installs fake modules into sys.modules before autodoc imports your code, but Python's import system consults sys.modules by top-level name first: mocking 'heavylib' makes 'import heavylib.sub' resolve through the fake, while mocking only 'heavylib.sub' leaves the real top-level import to fail. The setting is also read only when the autodoc extension is active, which is why a missing extension entry makes the whole list a no-op.

Edge cases

• Mocks stub the import, not behavior: code that subclasses a mocked class or calls mocked functions at import time can still fail; that needs a real install or restructuring the import behind a function.
• Never mock stdlib modules or modules your Sphinx extensions themselves import; you will break the build in confusing ways.
• Mocked objects render with limited signatures in the docs; for public API pages prefer a real install and reserve mocks for genuinely heavy optional dependencies.

Provenance

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