sphinx-autodoc-typehints
Type hints (PEP 484) support for the Sphinx autodoc extension
Decision gist · record as of 2026-08-14
Yes. This is a stable, actively maintained extension (release 11 days ago, 587 stars) with low install friction and no known vulnerabilities. It solves a real problem—eliminating type duplication between code and docs—and is widely used (top 5000 on PyPI). MIT license poses no restrictions. Install it if you use Sphinx and want your type hints to flow automatically into your documentation.AI-flagged interpretation of the facts on this page — verify before relying
Before you install
- Requires Python 3.12 or later and an existing Sphinx documentation setup.
- Low friction: pure Python wheel with a single runtime dependency on sphinx.
- Active maintenance with a release 11 days ago and 587 repository stars.
License · maintenance · safety
MIT (permissive) — MIT license permits commercial and private use with minimal restrictions—suitable for most projects.
last release 2026-08-03 (11 days) · last repo commit 2026-08-11 · 587 stars
0 known vulnerabilities (OSV.dev, 2026-08-14) · 9,483,648 downloads/mo, #1,530 on PyPI
Alternatives
Verify before relying
pip install sphinx-autodoc-typehints
# In conf.py:
extensions = ["sphinx.ext.autodoc", "sphinx_autodoc_typehints"]
# In your code:
def format_unit(value: float, unit: str) -> str:
"""Format a value with its unit."""
return f"{value} {unit}"- Whether the extension handles all edge cases in complex type hierarchies (e.g., deeply nested generics, forward references).
- Performance impact when processing large codebases with thousands of annotated functions.
What it is and what it does
sphinx-autodoc-typehints is a Sphinx extension that reads Python type annotations from your source code and automatically incorporates them into your generated API documentation. Instead of writing types twice—once in code annotations and again in docstrings—you write them once in your function signatures and let the extension handle the rest. It resolves types from TYPE_CHECKING blocks and .pyi stub files, renders @overload signatures, extracts types from attrs and dataclass classes, and handles both Google and NumPy docstring styles.
The extension integrates directly into your Sphinx build pipeline through sphinx.ext.autodoc. It offers fine-grained control over how types appear in your output: you can choose union display style (Union[X, Y] vs X | Y), show or hide return types, display default parameter values, and apply custom type formatters. It also automatically fixes cross-references for standard library types whose runtime module differs from their documented path, reducing manual link corrections in your docs.
Use it for
- Maintain API documentation for a library without duplicating type information between code and docstrings.
- Generate type-annotated docs for attrs or dataclass-heavy projects automatically.
- Support multiple docstring styles (Google, NumPy, reStructuredText) while keeping types in sync.
- Display @overload signatures in your docs to show all valid function call patterns.
- Control union type rendering to match your project's style guide (Union syntax vs pipe syntax).
Worth the install?
AI-flagged interpretation of the facts on this page. Verify before relying on it.
Yes.
This is a stable, actively maintained extension (release 11 days ago, 587 stars) with low install friction and no known vulnerabilities. It solves a real problem—eliminating type duplication between code and docs—and is widely used (top 5000 on PyPI). MIT license poses no restrictions. Install it if you use Sphinx and want your type hints to flow automatically into your documentation.
Install
sphinx-autodoc-typehints on PyPI
Before you install
Low friction: pure Python wheel with a single runtime dependency on sphinx. Active maintenance with a release 11 days ago and 587 repository stars.
Requires Python 3.12 or later and an existing Sphinx documentation setup.
License in practice
MIT license permits commercial and private use with minimal restrictions—suitable for most projects.
Quickstart
pip install sphinx-autodoc-typehints
# In conf.py:
extensions = ["sphinx.ext.autodoc", "sphinx_autodoc_typehints"]
# In your code:
def format_unit(value: float, unit: str) -> str:
"""Format a value with its unit."""
return f"{value} {unit}"Verify before relying
- Whether the extension handles all edge cases in complex type hierarchies (e.g., deeply nested generics, forward references).
- Performance impact when processing large codebases with thousands of annotated functions.
Package facts
| License | MIT permissive |
| Python support | Supports the current Python release >=3.12 |
| Install friction | Low. Pure-Python wheel |
| Runtime dependencies | 1 packagesphinx |
| Maintenance | Actively maintained 11 days since the last release |
| Last repo commit | |
| First released | |
| Downloads | 9,483,648 / month, #1,530 on PyPI 30-day window, as of 2026-08-14 |
| Known vulnerabilities | None known OSV.dev, checked 2026-08-14 |
| Classifiers | Development Status :: 5 - Production/StableFramework :: Sphinx :: ExtensionIntended Audience :: DevelopersLicense :: OSI Approved :: MIT LicenseProgramming Language :: PythonProgramming Language :: Python :: 3 :: OnlyProgramming Language :: Python :: 3.12Programming Language :: Python :: 3.13Programming Language :: Python :: 3.14Programming Language :: Python :: 3.15Topic :: Documentation :: Sphinx |
Evidence: sphinx_autodoc_typehints-3.13.2-py3-none-any.whl
Tags
Let your AI agent find packages like this
Example. Real query, live index.
You found this page by searching. An agent finds it by wishing: SkillFed indexes 14,416 PyPI packages by what they can do, searchable in plain language.
wish › “sphinx type hints documentation”
- sphinx-autodoc-typehintsAutomatically extracts Python type hints from your code and injects…
- sphinx-toolboxSphinx-toolbox extends Sphinx with a collection of utility extensions…
- enum-toolsProvides utilities to enhance Python's enum module with better Sphinx…
Give your agent the search over MCP, or paste the wish link into any chat.
More Sphinx packages
Parses Python docstrings in ReST, Google, Numpydoc, and Epydoc formats, extracting structured information like descriptions, parameters, return types, and exceptions.
Install it if you need to programmatically read and extract structured data from Python docstrings.
Sphinx generates professional documentation from reStructuredText source files, producing HTML, PDF, EPUB, and other formats with automatic cross-references, code highlighting, and hierarchical navigation.
A Sphinx extension that outputs documentation in serialized HTML formats (JSON and pickle) alongside standard HTML.
Alabaster is a clean, responsive Sphinx theme for documentation that requires Python 3.10 or newer and Sphinx 6.2 or newer.
A Sphinx extension that generates HTML help files from reStructuredText documentation source.
A Sphinx extension that converts documentation source files into QtHelp format, enabling integration with Qt-based help systems and documentation viewers.
However, be aware that maintenance is dormant—if you rely on it long-term, monitor Sphinx compatibility and consider whether QtHelp remains the right format for your…
See also autodoc_pydantic · sphinx-autoapi · autodocsumm · sphinx-autodoc2 · sphinxcontrib-django · autoclasstoc · readthedocs-sphinx-search · sphinx_tippy · sphinx-click · sphinxcontrib-napoleon