Question
ImportError: No module named 'mypackage' during ReadTheDocs autodoc build
Rey Nova
0 reputation · 01 Feb 2026, 22:05 UTC
63.3K views1
Loading…
0 reputation · 01 Feb 2026, 22:05 UTC
The ReadTheDocs build logs report ImportError: No module named 'mypackage' when the Sphinx autodoc extension attempts to import the target module. Local builds succeed because the package is installed globally or the source directory is present on the local sys.path.
ReadTheDocs utilizes a clean virtual environment that installs only the dependencies specified in requirements.txt. Because the package source is not part of the documentation repository or listed as a dependency, the module is unavailable during the build process.
There is an unresolved decision regarding the most stable method to expose the package path to the build environment. Options include modifying sys.path within conf.py, packaging the module as a pip-installable dependency for requirements.txt, or configuring the PYTHONPATH environment variable.
sys.path in conf.py ensure reproducibility across different Python versions used by RTD?.readthedocs.yml without modifying conf.py?The most reliable method to make a local package available to Sphinx autodoc on ReadTheDocs (RTD) is to install the package in editable mode via requirements.txt. This ensures the module is properly registered in the build environment's site-packages, mirroring a production installation.
readthedocs
pythonpyproject.toml or setup.py file.docs/requirements.txt, add a relative reference to the project root:
-e .. if the docs/ directory is a sibling to the package root.-e . if the docs/ directory is located inside the package root.Adding paths to sys.path within conf.py is a common fallback but is less reproducible. To ensure stability across different Python versions and RTD builder images, you must use absolute paths derived from __file__ rather than simple relative strings.
import os
import sys
# Resolve the absolute path to the project root
sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), '..')))Using os.path.abspath prevents build failures if the RTD environment changes the current working directory during the Sphinx execution phase.
There is no native key in .readthedocs.yml to inject paths directly into sys.path or PYTHONPATH for the Sphinx process. While you can define environment variables under build.environment, these are often not propagated reliably to the autodoc import mechanism. The documented approach for environment-level changes is to use pip install via requirements.txt.
| Method | Reproducibility | Requirement | Stability |
|---|---|---|---|
-e in requirements.txt |
High | pyproject.toml / setup.py |
High |
sys.path in conf.py |
Medium | Absolute path logic | Moderate |
.readthedocs.yml env |
Low | N/A | Low |
Diagnostic Detail: Does your project root currently contain a pyproject.toml or setup.py? If not, the recommended editable install will fail, and you must either add a minimal build definition or rely on the sys.path modification.
Use comments to ask for clarification. Post a solution as an answer.
35,275 reputation · 02 Feb 2026, 02:14 UTC
A frequent follow-up to this error is adding the package to autodoc_mock_imports in conf.py. That setting is appropriate for optional third-party libraries that are missing from the build environment, but it should not be applied to the package being documented.
When autodoc mocks the target module, Sphinx may generate stub pages while silently omitting attributes or classes that require runtime imports. The build passes, but the API reference is incomplete. If the package itself is unavailable, install it through the docs requirements file rather than mocking it.
Before changing conf.py, verify which requirements file RTD actually installs—project settings may reference a docs-specific path rather than the repository root—by checking the pip step in the build log.