Install & Compatibility
Where this runs
tested against v1.10.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.000s · 92.9MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 5.7s · import 0.000s · 93MB
95MB installed
● package 95MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
numpydoc
✓ # In your Sphinx conf.py file:
extensions = [
'sphinx.ext.autodoc',
'sphinx.ext.autosummary', # Automatically loaded by numpydoc
'numpydoc'
]
numpydoc is a Sphinx extension, not a Python library imported for direct application use. It's added to the 'extensions' list in Sphinx's conf.py to enable its features.
To use numpydoc, you primarily need to add 'numpydoc' to the `extensions` list in your Sphinx `conf.py` file. This enables NumPy-style docstring parsing. You typically use it alongside `sphinx.ext.autodoc` for automatic documentation generation. Other common extensions like `sphinx.ext.autosummary` are often used and are automatically loaded by numpydoc.
# conf.py (in your Sphinx project's docs/source directory)
import os
import sys
# If your project is a package, add its path to sys.path
# sys.path.insert(0, os.path.abspath('../../src')) # Example for a 'src' directory two levels up
project = 'My Project'
copyright = '2026, Your Name'
author = 'Your Name'
release = '0.1'
extensions = [
'sphinx.ext.autodoc',
'sphinx.ext.autosummary',
'sphinx.ext.coverage',
'sphinx.ext.mathjax',
'sphinx.ext.viewcode',
'numpydoc'
]
templates_path = ['_templates']
exclude_patterns = []
html_theme = 'alabaster'
html_static_path = ['_static']
# Numpydoc specific configuration (optional, set as needed)
numpydoc_show_class_members = False
numpydoc_class_members_toctree = False
numpydoc_xref_param_type = True
# To enable validation of docstrings during build
numpydoc_validation_checks = {"all"}
numpydoc --version
Debug
Known issues
breakingnumpydoc version 1.10.0 and later require Python 3.10+. Support for Python 3.9 and earlier has been dropped. Version 1.6.0 introduced a requirement for Python 3.8+.fixUpgrade your Python environment to 3.10 or newer. If you need to use an older Python, pin numpydoc to a compatible version (e.g., `<1.10.0` for Python 3.9).
affects: >=1.10.0 (Python 3.10+); >=1.6.0 (Python 3.8+)
breakingnumpydoc version 1.10.0 and later require Sphinx 6+. Earlier versions (e.g., 1.6.0) required Sphinx 5+, and even older versions had lower requirements (e.g., 1.2.1 required Sphinx 1.8+).fixEnsure your Sphinx installation meets the minimum version requirement for your numpydoc version. Upgrade Sphinx to 6.0 or newer for numpydoc 1.10.0.
affects: >=1.10.0 (Sphinx 6+); >=1.6.0 (Sphinx 5+)
deprecatedThe `numpydoc_edit_link` configuration option was deprecated in version 1.3rc1 and subsequently removed. Its functionality for inserting an edit link is now handled via HTML templates.fixRemove `numpydoc_edit_link` from your `conf.py`. If you need an edit link, configure it directly within your Sphinx HTML theme templates.
affects: >=1.3.1
gotchanumpydoc introduced support for configuration via `pyproject.toml` in version 1.6.0, with enhancements (e.g., `exclude_files` for validation) in 1.10.0. While `conf.py` remains the primary config, users transitioning or with complex build systems should be aware of `pyproject.toml` options.fixReview numpydoc's documentation for `pyproject.toml` configuration options, particularly if you manage project metadata or build settings via `pyproject.toml`.
affects: >=1.6.0
gotchaThe command-line interfaces (CLIs) for numpydoc were unified in version 1.8.0. If you were using separate or older CLI commands, they might have changed.fixConsult the numpydoc documentation for the updated CLI usage. Adjust any scripts or automation that invoke numpydoc's command-line tools.
affects: >=1.8.0
gotchaCSS styling for definition lists changed significantly in numpydoc versions less than 0.8 and Sphinx versions less than 2.0. This can cause rendering issues, especially with themes like `sphinx-rtd-theme`.fixIf experiencing rendering issues, particularly with definition lists, ensure both numpydoc and Sphinx are updated to recent versions. Custom CSS might be required for older setups.
affects: <0.8 (numpydoc) or <2.0 (Sphinx)
Upgrade
Version history
1.10.0latest on PyPI · released Dec 2, 2025
Audit
Dependencies
PythonrequiredRequired runtime environment.
SphinxrequiredCore documentation generator that numpydoc extends.