---
id: sphinx-autodoc-typehints
version: "3.13.2"
license: MIT
license_treatment: permissive
maintenance: active
---

# sphinx-autodoc-typehints — Type hints (PEP 484) support for the Sphinx autodoc extension

License: permissive · Maintenance: active · Downloads: 9.5M/mo

## 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 above — verify before relying.

Automatically extracts Python type hints from your code and injects them into Sphinx-generated documentation, eliminating the need to duplicate type information in docstrings.

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

pip install sphinx-autodoc-typehints
uv add sphinx-autodoc-typehints
poetry add sphinx-autodoc-typehints

## Installing sphinx-autodoc-typehints

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.

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}"

Requires Python 3.12 or later and an existing Sphinx documentation setup.

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_current
- Install friction: low
- Maintenance: active
- Downloads: 9.5M/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

sphinx type hints documentation, autodoc type annotations, python type hints sphinx, automatic type documentation, sphinx extension type hints, pep 484 sphinx autodoc, type annotation docs generator, sphinx-extension, type-hints, api-docs

[View on SkillFed](https://skillfed.io/packages/sphinx-autodoc-typehints) · [View on PyPI](https://pypi.org/project/sphinx-autodoc-typehints/)