sphinx-build: extension 'sphinx.ext.autodoc' has no setup() failed

Not specified by the original author.

Fix Sphinx extension "has no setup()" failure for autodoc

TL;DR

Sphinx imported something named like the extension but it was not the real one, almost always a local file or package shadowing sphinx.ext.autodoc, or sphinx-build running from a different Python environment than the one where Sphinx is installed. Remove or rename the shadowing module (or fix the environment), then rebuild. The extension loads because the import now resolves to the real Sphinx package.

The error

Extension error:
Extension 'sphinx.ext.autodoc' has no setup() function.

Steps

1. Check what the name resolves to in the build environment: python -c "import sphinx.ext.autodoc; print(sphinx.ext.autodoc.__file__)" using the same Python that runs sphinx-build. Expected: a path under site-packages. If it prints a path inside your repo, that file is shadowing the real extension.

2. Hunt the shadow: find docs -maxdepth 3 -name "sphinx*" -o -maxdepth 3 -name "autodoc*", and check conf.py for sys.path.insert lines that put your own directories first. Rename or remove the shadowing module or package (e.g. a docs/sphinx/ directory or an autodoc.py helper). Expected: no local module or package named sphinx or autodoc remains on the path conf.py sets up.

3. If the import itself fails in step 1, reinstall: pip install sphinx or pip install --force-reinstall sphinx. Expected: step 1 now prints the site-packages path.

4. Confirm the binary matches the environment: which sphinx-build and the shebang line at the top of that file should point at the same Python you tested. Expected: one Python environment owns both sphinx-build and the installed Sphinx.

5. Rebuild: sphinx-build -b html docs docs/_build. Expected: no 'has no setup()' error; the build proceeds past extension loading.

Use this when

• any Sphinx extension fails with 'has no setup()' (the fix is the same for other extensions)
• the build dies before reading any source files
• you recently added a helper module named sphinx, autodoc, or similar

Not for this skill when

• ModuleNotFoundError for a third-party extension (that means it is not installed at all)
• an ImportError raised inside the extension's own setup() (different failure, read the traceback)
• theme errors like 'no theme named' (theme problem, not extension loading)

Variant phrasings

• sphinx extension has no setup function
• sphinx-build extension error autodoc
• Could not import extension sphinx.ext.autodoc
• sphinx ExtensionError has no setup

Why it happens

When Sphinx loads an extension it imports the module and calls its setup() function. The 'has no setup()' error means the import succeeded but returned the wrong module: Python found your local sphinx.py, sphinx/ package, or autodoc.py before the installed Sphinx because conf.py inserted your directories at the front of sys.path. The other classic cause is two Python environments: sphinx-build from one, Sphinx installed in another.

Edge cases

• A directory named sphinx/ anywhere on sys.path shadows the whole package, not just one module; check for those first.
• Virtualenv mixups are silent: head -1 $(which sphinx-build) shows which interpreter the script uses.
• After renaming a shadowing file, delete stale pycache directories or the old bytecode can still shadow.

Provenance

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

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

Thread query: sphinx-build: extension 'sphinx.ext.autodoc' "has no setup()" failed

TL;DR: Sphinx imported something named like the extension but it was not the real one, almost always a local file or package shadowing sphinx.ext.autodoc, or sphinx-build running from a different Python environment than the one where Sphinx is installed. Remove or rename the shadowing module (or fix the environment), then rebuild. The extension loads because the import now resolves to the real Sphinx package.

Not specified by the original author.

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.

2. 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.

3. 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.

4. 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

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

Thread query: sphinx autodoc: "failed to import module" error

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.

Not specified by the original author.

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.

2. 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.

3. 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

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

Thread query: sphinx mock_imports not working, autodoc import error persists

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.