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.

Installation
Quick start
How-to guides
Reference
- Configuration options
- Warning categories
Explanation
- How it works
- How return type options interact

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. When the block imports a dependency your docs environment lacks, the extension mocks it the way autodoc_mock_imports would, so its types still render as cross-references; install it when you want those references to resolve. A statement raises a warning when it fails for another reason, such as a dependency you have installed but that fails to import. Fix the environment, or suppress it:

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 custom type formatter

To control exactly how a type appears in your docs, provide a formatter function. It receives the type annotation and the Sphinx config, and returns RST markup (or None to use the default rendering):

def my_formatter(annotation, config):
    if annotation is bool:
        return ":class:`bool`"
    return None


typehints_formatter = my_formatter

To always show the full module path for types (e.g., collections.OrderedDict instead of OrderedDict):

typehints_fully_qualified = True

Document a `NewType` or `type` alias without expanding it

The extension preserves alias names only when they have a .. py:type:: directive in your docs. Without that entry, the alias is expanded to its underlying type. Add a documentation entry for the alias, and it will render as a clickable link instead.

Add types for C extensions or packages without annotations

The extension reads .pyi stub files automatically. Place a .pyi file next to the .so/.pyd file (or as __init__.pyi in the package directory) with the type annotations, and they'll be picked up.

Fix cross-reference links for stdlib types

Many Python stdlib classes have a __module__ that points to an internal module rather than their public documented path. For example, threading.local reports its module as _thread._local, and concurrent.futures.Executor as concurrent.futures._base.Executor. This produces broken cross-reference links because the extension builds links from __module__.__qualname__.

When intersphinx is enabled, the extension automatically fixes this. After intersphinx loads its inventories, it builds a reverse mapping from runtime paths to documented paths and applies it during annotation formatting. No configuration is needed — just make sure intersphinx is loaded:

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

intersphinx_mapping = {
    "python": ("https://docs.python.org/3", None),
}

With this, a type hint like threading.local correctly links to threading.local in the Python docs instead of producing a broken _thread._local reference.

Fix cross-reference links for renamed modules

Some third-party libraries expose types under a different module path than where they're documented. For example, GTK types live at gi.repository.Gtk.Window in Python, but their docs list them as Gtk.Window. This causes broken intersphinx links.

Use typehints_fixup_module_name to rewrite the module path before links are generated:

def fixup_module_name(module: str) -> str:
    if module.startswith("gi.repository."):
        return module.removeprefix("gi.repository.")
    return module


typehints_fixup_module_name = fixup_module_name

Suppress warnings

To silence all warnings from this extension:

suppress_warnings = ["sphinx_autodoc_typehints"]

To suppress only specific warning types, see Warning categories for the full list.

Reference

Configuration options

Option	Default	Description
`typehints_document_rtype`	`True`	Show the return type in docs.
`typehints_document_rtype_none`	`True`	Show return type when it's `None`.
`typehints_document_overloads`	`True`	Show `@overload` signatures in docs. Use `:no-overloads:` in a docstring for per-function control.
`typehints_use_rtype`	`True`	Show return type as a separate block. When `False`, it's inlined with the return description.
`always_use_bars_union`	`False`	Use `X \| Y` instead of `Union[X, Y]`. Always on for Python 3.14+.
`simplify_optional_unions`	`True`	Flatten `Optional[Union[A, B]]` to `Union[A, B, None]`.
`typehints_defaults`	`None`	Show default values: `"comma"`, `"braces"`, or `"braces-after"`.
`typehints_use_signature`	`False`	Keep parameter types in the function signature.
`typehints_use_signature_return`	`False`	Keep the return type in the function signature.
`typehints_fully_qualified`	`False`	Show full module path for types (e.g., `module.Class` not `Class`).
`always_document_param_types`	`False`	Add types even for parameters that don't have a `:param:` entry in the docstring.
`typehints_formatter`	`None`	A function `(annotation, Config) -> str \| None` for custom type rendering.
`typehints_fixup_module_name`	`None`	A function `(str) -> str` to rewrite module paths before generating cross-reference links.

Warning categories

All warnings can be suppressed via Sphinx's suppress_warnings in conf.py:

Category	When it's raised
`sphinx_autodoc_typehints`	Catch-all for every warning from this extension.
`sphinx_autodoc_typehints.comment`	A type comment (`# type: ...`) couldn't be parsed.
`sphinx_autodoc_typehints.forward_reference`	A forward reference (string annotation) couldn't be resolved.
`sphinx_autodoc_typehints.guarded_import`	A `TYPE_CHECKING` statement failed for a reason other than an absent dependency.
`sphinx_autodoc_typehints.local_function`	A type annotation references a function defined inside another function.
`sphinx_autodoc_typehints.multiple_ast_nodes`	A type comment matched multiple definitions and the right one is ambiguous.

Explanation

How it works

During the Sphinx build, this extension hooks into two autodoc events. First, it strips type annotations from function signatures (so they don't appear twice). Then, it reads the annotations and adds type information into the docstring -- parameter types go next to each :param: entry, and the return type becomes an :rtype: entry.

Only parameters that already have a :param: line in the docstring get type information added. Set always_document_param_types = True to add types for all parameters, even undocumented ones.

How return type options interact

The return type options combine as follows:

Both defaults (typehints_document_rtype = True, typehints_use_rtype = True) -- return type appears as a separate :rtype: block below the description.
Inline mode (typehints_document_rtype = True, typehints_use_rtype = False) -- return type is appended to the :return: text. If there's no :return: entry, it falls back to a separate block.
Disabled (typehints_document_rtype = False) -- no return type shown, regardless of other settings.
Skip None (typehints_document_rtype_none = False) -- hides None return types specifically, other return types still appear.

Release files for sphinx-autodoc-typehints 3.13.7

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for sphinx-autodoc-typehints 3.13.7
File	Size	Uploaded
sphinx_autodoc_typehints-3.13.7.tar.gz	97.0 kB	Sep 18, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for sphinx-autodoc-typehints 3.13.7
File	Interpreter	ABI	Platform	Reset
sphinx_autodoc_typehints-3.13.7-py3-none-any.whl 49.3 kB Sep 18, 2026	Python 3	none	any	Details

Total release size: 146.3 kB

Release files / sphinx_autodoc_typehints-3.13.7.tar.gz

Download URL	sphinx_autodoc_typehints-3.13.7.tar.gz
Size	97.0 kB
Tags	Source
SHA-256 checksum How to use checksums	`c090ee6cb2c9e0a86074be9c288915ea3519e0992c77c5fb3b00fbfe61d50d1f`
BLAKE2b-256 checksum How to use checksums	`2bd169ddd9bad8965986d11f92f9526f81e0805936763d34aed5e5b1e80795d1`
Upload date	Sep 18, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/tox-dev/sphinx-autodoc-typehints
Publishing commit: github.com/tox-dev/sphinx-autodoc-typehints/tree/2368e22f0f330ce3e91938b4ff647685bc08dd62

Workflow

Publishing configuration: github.com/tox-dev/sphinx-autodoc-typehints/blob/2368e22f0f330ce3e91938b4ff647685bc08dd62/.github/workflows/release.yaml
Publishing logs: github.com/tox-dev/sphinx-autodoc-typehints/actions/runs/35297919502/attempts/1

Artifact

Subject: sphinx_autodoc_typehints-3.13.7.tar.gz
SHA-256 checksum: c090ee6cb2c9e0a86074be9c288915ea3519e0992c77c5fb3b00fbfe61d50d1f Verifying attestations

Release files / sphinx_autodoc_typehints-3.13.7-py3-none-any.whl

Download URL	sphinx_autodoc_typehints-3.13.7-py3-none-any.whl
Size	49.3 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`7367a6736a0d779bfee4533217fa784b6cadb4f5466b5ea47e722e9fcf0946e8`
BLAKE2b-256 checksum How to use checksums	`660c3ee05b107b8c58b41e5df954a8354a9f1db5c334299be5167a5a77df6369`
Upload date	Sep 18, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/tox-dev/sphinx-autodoc-typehints
Publishing commit: github.com/tox-dev/sphinx-autodoc-typehints/tree/2368e22f0f330ce3e91938b4ff647685bc08dd62

Workflow

Publishing configuration: github.com/tox-dev/sphinx-autodoc-typehints/blob/2368e22f0f330ce3e91938b4ff647685bc08dd62/.github/workflows/release.yaml
Publishing logs: github.com/tox-dev/sphinx-autodoc-typehints/actions/runs/35297919502/attempts/1

Artifact

Subject: sphinx_autodoc_typehints-3.13.7-py3-none-any.whl
SHA-256 checksum: 7367a6736a0d779bfee4533217fa784b6cadb4f5466b5ea47e722e9fcf0946e8 Verifying attestations