sphinx-autodoc-typehints

This Sphinx extension reads your Python type hints and automatically adds type information to your generated documentation -- so you write types once in code and they appear in your docs without duplication.

Features:

• Adds parameter and return types from annotations into docstrings
• Resolves types from TYPE_CHECKING blocks and .pyi stub files
• Renders @overload signatures in docstrings
• Extracts types from attrs and dataclass classes
• Shows default parameter values alongside types
• Controls union display style (Union[X, Y] vs X | Y)
• Automatically fixes cross-references for stdlib types whose runtime module differs from their documented path
• Supports custom type formatters and module name rewriting
• Extracts descriptions from Annotated[T, Doc(...)] metadata
• Works with Google and NumPy docstring styles

Sphinx has a built-in autodoc_typehints setting (since v2.1) that can move type hints between signatures and descriptions. This extension replaces that with the features above. See Avoid duplicate types with built-in Sphinx.

<!-- mdformat-toc start --slug=github --no-anchors --maxlevel=6 --minlevel=2 -->

• Installation
• Quick start
• How-to guides
  • Avoid duplicate types with built-in Sphinx
  • Use with Google or NumPy docstring style
  • Control return type display
  • Change how union types look
  • Show default parameter values
  • Control overload signature display
  • Keep type hints in function signatures
  • Handle circular imports
  • Resolve types from TYPE_CHECKING blocks
  • Show types for attrs or dataclass fields
  • Write a custom type formatter
  • Document a NewType or type alias without expanding it
  • Add types for C extensions or packages without annotations
  • Fix cross-reference links for stdlib types
  • Fix cross-reference links for renamed modules
  • Suppress warnings
• Reference
  • Configuration options
  • Warning categories
• Explanation
  • How it works
  • How return type options interact

<!-- mdformat-toc end -->

Installation

pip install sphinx-autodoc-typehints

Then add the extension to your conf.py:

extensions = ["sphinx.ext.autodoc", "sphinx_autodoc_typehints"]

Quick start

Instead of writing types in your docstrings, write them as Python type hints. The extension picks them up and adds them to your Sphinx output:

# Before: types repeated in docstrings
def format_unit(value, unit):
    """
    Format a value with its unit.

    :param float value: a numeric value
    :param str unit: the unit (kg, m, etc.)
    :rtype: str
    """
    return f"{value} {unit}"


# After: types only in annotations, docs generated automatically
def format_unit(value: float, unit: str) -> str:
    """
    Format a value with its unit.

    :param value: a numeric value
    :param unit: the unit (kg, m, etc.)
    """
    return f"{value} {unit}"

The extension adds the type information to your docs during the Sphinx build. See an example at the pyproject-api docs.

How-to guides

Avoid duplicate types with built-in Sphinx

If types appear twice in your docs, you're likely running both this extension and Sphinx's built-in type hint processing. Set autodoc_typehints = "none" in your conf.py to let this extension handle everything:

autodoc_typehints = "none"

Use with Google or NumPy docstring style

If you use sphinx.ext.napoleon for Google-style or NumPy-style docstrings, load it before this extension:

extensions = [
    "sphinx.ext.autodoc",
    "sphinx.ext.napoleon",
    "sphinx_autodoc_typehints",
]

To avoid duplicate return type entries, disable the return type block in both extensions:

napoleon_use_rtype = False  # sphinx.ext.napoleon setting
typehints_use_rtype = False

See napoleon_use_rtype in the Sphinx docs.

Control return type display

By default, return types appear as a separate block in your docs. You can change this:

# Don't show return types at all
typehints_document_rtype = False

# Don't show "None" return types, but show all others
typehints_document_rtype_none = False

# Show the return type inline with the return description
# instead of as a separate block
typehints_use_rtype = False

Change how union types look

By default, union types display as Union[str, int] and Optional[str]. To use the shorter pipe syntax (str | int, str | None):

always_use_bars_union = True

On Python 3.14+, the pipe syntax is always used regardless of this setting.

By default, Optional[Union[A, B]] is simplified to Union[A, B, None]. To keep the Optional wrapper:

simplify_optional_unions = False

Note: with this set to False, any union containing None will display as Optional.

Show default parameter values

To include default values in your docs, set typehints_defaults to one of three styles:

# "param (int, default: 1) -- description"
typehints_defaults = "comma"

# "param (int) -- description (default: 1)"
typehints_defaults = "braces"

# "param (int) -- description (default: 1)"  (at end of text)
typehints_defaults = "braces-after"

Control overload signature display

When a function has @overload signatures, they are rendered automatically in the docstring. To disable this globally:

typehints_document_overloads = False

To disable overloads for a single function while keeping them everywhere else, add :no-overloads: to the docstring:

@overload
def f(x: int) -> str: ...
@overload
def f(x: str) -> bool: ...
def f(x):
    """:no-overloads:

    f accepts int or str, see docs for details.
    """

The :no-overloads: directive is stripped from the rendered output.

Keep type hints in function signatures

By default, type hints are removed from function signatures and shown in the parameter list below. To keep them visible in the signature line:

typehints_use_signature = True  # show parameter types in signature
typehints_use_signature_return = True  # show return type in signature

Handle circular imports

When two modules need to reference each other's types, you'll get circular import errors. Fix this by using from __future__ import annotations, which makes all type hints strings that are resolved later:

from __future__ import annotations

import othermodule


def process(item: othermodule.OtherClass) -> None: ...

Resolve types from TYPE_CHECKING blocks

This extension automatically imports types from TYPE_CHECKING blocks at doc-build time. If a type still fails to resolve, the dependency is likely not installed in your docs environment. Either install it, or suppress the warning:

suppress_warnings = ["sphinx_autodoc_typehints.guarded_import"]

Show types for attrs or dataclass fields

The extension backfills annotations from attrs field metadata automatically. For dataclasses, annotations are read from the class body. Make sure the class is documented with .. autoclass:: and :members: or :undoc-members:.

Write a cust