Sphinx autodoc "failed to import module" in CI

sphinx.ext.autodoc imports your modules at build time to extract docstrings. The import failed, usually because the project or one of its runtime dependencies is not installed in the docs environment.

What this error means

sphinx-build warns "autodoc: failed to import module 'X'; the following exception was raised:" followed by a traceback, commonly a ModuleNotFoundError.

WARNING: autodoc: failed to import module 'mypkg.core'; the following exception was raised:
No module named 'numpy'

Common causes

The project is not installed in the docs env

autodoc must import your package; if it was not installed (for example via pip install -e .), the import fails.

A runtime dependency is missing

The module imports a third-party package at top level that the docs environment did not install, so the import raises before autodoc can read docstrings.

How to fix it

Install the project and its dependencies

1. Install your package (editable) into the docs environment.
2. Install its runtime dependencies so top-level imports succeed.
3. Rebuild so autodoc can import the modules.

pip install -e .
pip install -r docs/requirements.txt
sphinx-build -b html docs docs/_build/html

Mock heavy imports with autodoc_mock_imports

For dependencies you cannot install in docs CI, mock them so autodoc imports the module without them.

# conf.py
autodoc_mock_imports = ["numpy", "torch"]

How to prevent it

• Install the package (editable) in the docs build environment.
• Keep runtime deps that autodoc needs in docs requirements.
• Use autodoc_mock_imports for heavy optional dependencies.

Related guides