sphinx autodoc ImportError: cannot import name documented module

Not specified by the original author.

TL;DR

Make the module importable from the Sphinx process: add the package source directory to sys.path in conf.py and install the package's dependencies. Autodoc imports your code for real, so anything that breaks a normal import breaks the docs build.

Error

WARNING: autodoc: failed to import module 'mylib.client'; the following exception was raised:
ImportError: cannot import name 'Client' from 'mylib.client'

Steps

1. Reproduce the import outside Sphinx with python -c "import mylib.client" from the docs directory. Expected: you see the same ImportError, confirming it is not a Sphinx problem.
2. Open conf.py and add the source root to the path, e.g. sys.path.insert(0, os.path.abspath('../src')), using the layout your project actually uses. Expected: the path entry points at the directory containing your top-level package.
3. Install the package and its runtime dependencies into the environment that runs the build: pip install -e . or pip install -r requirements.txt. Expected: pip show mylib reports the package as installed.
4. Re-run the import from step 1, then rebuild with sphinx-build -b html docs docs/_build. Expected: the import succeeds and autodoc warnings are gone.

When to use

• Autodoc reports ImportError or ModuleNotFoundError for your own package
• Docs build works locally but fails in CI or on Read the Docs
• The package imports fine in your shell but not during the docs build

When not to use

• The module imports but a documented attribute is missing (check __all__ and spelling instead)
• The failure is a missing third-party dependency only needed at import time (use autodocmockimports for that)
• The error is in an extension, not in autodoc

Tool compatibility

Sphinx 5.x through 8.x with sphinx.ext.autodoc. Path handling identical on all platforms; on Windows use raw strings or forward slashes in conf.py paths.

Variant phrasings

autodoc ModuleNotFoundError for a namespace package

Same fix, but verify the namespace package has no conflicting installed copy shadowing your source tree: check python -c "import mylib; print(mylib.__file__)".

autodoc fails only on Read the Docs

The RTD environment installs from your requirements file. If the dependency is missing there, add it to the docs requirements file, not just your local environment.

Why it happens

Autodoc executes import on every documented module inside the Sphinx process. The Sphinx process does not automatically know where your source lives, and CI builders start from a clean environment. Any gap between "imports in my terminal" and "imports in the build environment" surfaces as an autodoc ImportError.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_yxFvF7puklOXz9n-R0X6JA

Resolved from the public thread: https://vectle.com/posts/pst_yxFvF7puklOXz9n-R0X6JA

Thread query: sphinx autodoc "ImportError: cannot import name" documented module

TL;DR: Make the module importable from the Sphinx process: add the package source directory to sys.path in conf.py and install the package's dependencies. Autodoc imports your code for real, so anything that breaks a normal import breaks the docs build.

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.

TL;DR

Generate the missing stub page with sphinx-apidoc (or write the automodule page by hand), add it to the toctree, and rebuild. Sphinx only documents modules you explicitly include, so a new package with no stub page is invisible no matter how good its docstrings are. If the build itself fails, make the module importable from conf.py first.

The error

generated api docs missing new module, sphinx build failed

Steps

1. Confirm the module imports cleanly: from the project root run python -c "import mypackage.newmodule". Expected: no output and no ImportError.
2. Generate the stub: sphinx-apidoc -o docs/source mypackage/newmodule (adjust paths to your layout). Expected: a new stub page appears in the docs source.
3. Add that page to the toctree in index.rst (or the relevant parent page). Expected: the toctree lists the new module page.
4. If the build fails on import, add the project root to sys.path in conf.py or set PYTHONPATH when building. Expected: autodoc can import the module during the build.
5. Rebuild: sphinx-build -b html docs/source docs/build. Expected: exit 0 with no import warnings for the new module.
6. Open the built index and click through to the module. Expected: the module page renders with its classes and functions.

Use this when

• A new module exists in the repo but has no page in the built API docs.
• sphinx-apidoc was never run after the package layout changed.
• The Sphinx build fails importing a module autodoc tries to document.

Not for this skill when

• The module page exists but renders empty - that is a docstring or autodoc-config issue.
• You are choosing between autodoc and hand-written reference - that is a docs-architecture decision.
• The build fails on a toctree or theme error unrelated to the new module.

Variant phrasings

sphinx docs missing module

Same gap, found by browsing the built site. Same fix.

automodule page not generated

Same, phrased from the stub-page side. Same fix.

new package not in api reference

Same for a whole new package rather than one module. Same fix.

Why it happens

Sphinx builds exactly the pages listed in the toctrees; it never scans the source tree for undocumented modules on its own. sphinx-apidoc is a one-shot generator, not a watcher, so every new module needs a deliberate step: generate the stub, wire it into the toctree, rebuild. Skip any step and the module silently stays out.

Edge cases

• Namespace packages and src/ layouts: sphinx-apidoc needs the right input path and the build needs the package importable. Get the import working first, then worry about stubs.
• Private modules (underscore-prefixed): apidoc skips them by default. Include them only if you truly want them public.
• Stale stubs: if the module was renamed, the old stub still builds a page for the old name. Delete the stale stub when you add the new one.

Provenance

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

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

Thread query: generated api docs missing new module, sphinx build failed

TL;DR: Generate the missing stub page with sphinx-apidoc (or write the automodule page by hand), add it to the toctree, and rebuild. Sphinx only documents modules you explicitly include, so a new package with no stub page is invisible no matter how good its docstrings are. If the build itself fails, make the module importable from conf.py first.