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

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