# sphinx-autodoc-typehints

> Type hints (PEP 484) support for the Sphinx autodoc extension

- **URL**: https://www.freshcrate.ai/projects/sphinx-autodoc-typehints
- **Author**: pypi
- **Category**: Frameworks
- **Latest version**: `3.10.5` (2026-06-03)
- **License**: Unknown
- **Source**: https://github.com/tox-dev/sphinx-autodoc-typehints/releases
- **Homepage**: https://pypi.org/project/sphinx-autodoc-typehints/
- **Language**: Python
- **GitHub**: 586 stars, 109 forks
- **Registry**: pypi (`sphinx-autodoc-typehints`)
- **Tags**: `environments`, `isolated`, `pypi`, `testing`, `virtual`

## Description

# sphinx-autodoc-typehints

[![PyPI](https://img.shields.io/pypi/v/sphinx-autodoc-typehints?style=flat-square)](https://pypi.org/project/sphinx-autodoc-typehints/)
[![Supported Python versions](https://img.shields.io/pypi/pyversions/sphinx-autodoc-typehints.svg)](https://pypi.org/project/sphinx-autodoc-typehints/)
[![Downloads](https://pepy.tech/badge/sphinx-autodoc-typehints/month)](https://pepy.tech/project/sphinx-autodoc-typehints)
[![check](https://github.com/tox-dev/sphinx-autodoc-typehints/actions/workflows/check.yaml/badge.svg)](https://github.com/tox-dev/sphinx-autodoc-typehints/actions/workflows/check.yaml)

This [Sphinx](https://www.sphinx-doc.org/) extension reads your Python
[type hints](https://docs.python.org/3/library/typing.html) 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`](https://docs.python.org/3/library/typing.html#typing.TYPE_CHECKING) blocks and
  [`.pyi` stub files](https://typing.python.org/en/latest/spec/distributing.html#stub-files)
- Renders [`@overload`](https://docs.python.org/3/library/typing.html#typing.overload) signatures in docstrings
- Extracts types from [attrs](https://www.attrs.org/) and
  [dataclass](https://docs.python.org/3/library/dataclasses.html) 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(...)]`](https://typing-extensions.readthedocs.io/en/latest/#Doc)
  metadata
- Works with [Google and NumPy](https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html) docstring styles

Sphinx has a built-in
[`autodoc_typehints`](https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#confval-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](#avoid-duplicate-types-with-built-in-sphinx).

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

- [Installation](#installation)
- [Quick start](#quick-start)
- [How-to guides](#how-to-guides)
  - [Avoid duplicate types with built-in Sphinx](#avoid-duplicate-types-with-built-in-sphinx)
  - [Use with Google or NumPy docstring style](#use-with-google-or-numpy-docstring-style)
  - [Control return type display](#control-return-type-display)
  - [Change how union types look](#change-how-union-types-look)
  - [Show default parameter values](#show-default-parameter-values)
  - [Control overload signature display](#control-overload-signature-display)
  - [Keep type hints in function signatures](#keep-type-hints-in-function-signatures)
  - [Handle circular imports](#handle-circular-imports)
  - [Resolve types from `TYPE_CHECKING` blocks](#resolve-types-from-type_checking-blocks)
  - [Show types for `attrs` or `dataclass` fields](#show-types-for-attrs-or-dataclass-fields)
  - [Write a custom type formatter](#write-a-custom-type-formatter)
  - [Document a `NewType` or `type` alias without expanding it](#document-a-newtype-or-type-alias-without-expanding-it)
  - [Add types for C extensions or packages without annotations](#add-types-for-c-extensions-or-packages-without-annotations)
  - [Fix cross-reference links for stdlib types](#fix-cross-reference-links-for-stdlib-types)
  - [Fix cross-reference links for renamed modules](#fix-cross-reference-links-for-renamed-modules)
  - [Suppress warnings](#suppress-warnings)
- [Reference](#reference)
  - [Configuration options](#configuration-options)
  - [Warning categories](#warning-categories)
- [Explanation](#explanation)
  - [How it works](#how-it-works)
  - [How return type options interact](#how-return-type-options-interact)

<!-- mdformat-toc end -->

## Installation

```bash
pip install sphinx-autodoc-typehints
```

Then add the extension to your [`conf.py`](https://www.sphinx-doc.org/en/master/usage/configuration.html):

```python
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:

```python
# 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

## Recent releases

| Version | Date | Urgency | Changes |
| --- | --- | --- | --- |
| `3.10.5` | 2026-06-03 | High | <!-- Release notes generated using configuration in .github/release.yaml at main -->  ## What's Changed * process_signature: don't skip the first arg on bound instance methods by @ilia-kats in https://github.com/tox-dev/sphinx-autodoc-typehints/pull/705 * 🐛 fix(annotations): use class role for Ellipsis/NotImplementedType on 3.13+ by @gaborbernat in https://github.com/tox-dev/sphinx-autodoc-typehints/pull/707  ## New Contributors * @ilia-kats made their first contribution in https://githu |
| `3.10.3` | 2026-05-28 | High | <!-- Release notes generated using configuration in .github/release.yaml at main -->  ## What's Changed * Show version in error tracebacks by @kdeldycke in https://github.com/tox-dev/sphinx-autodoc-typehints/pull/687 * Support PEP 695 `type` statement and python 3.12+ `TypeAliasType` by @lochhh in https://github.com/tox-dev/sphinx-autodoc-typehints/pull/691 * Fix typehints_formatter cache warning by @RazerM in https://github.com/tox-dev/sphinx-autodoc-typehints/pull/696 * 🐛 fix(stubs): re |
| `3.10.2` | 2026-04-21 | Low | Imported from PyPI (3.10.2) |
| `3.10.1` | 2026-04-13 | Medium | <!-- Release notes generated using configuration in .github/release.yaml at main -->  ## What's Changed * 🐛 fix(resolver): surface hints for @no_type_check targets by @gaborbernat in https://github.com/tox-dev/sphinx-autodoc-typehints/pull/681   **Full Changelog**: https://github.com/tox-dev/sphinx-autodoc-typehints/compare/3.10.0...3.10.1 |
| `3.10.0` | 2026-04-09 | Medium | <!-- Release notes generated using configuration in .github/release.yaml at main -->  ## What's Changed * 🔒 ci(workflows): add zizmor security auditing by @gaborbernat in https://github.com/tox-dev/sphinx-autodoc-typehints/pull/672 * ✨ feat(resolver): auto-inject :vartype: for annotated instance vars by @gaborbernat in https://github.com/tox-dev/sphinx-autodoc-typehints/pull/678 * 🐛 fix(intersphinx): skip union aliases in type mapping by @gaborbernat in https://github.com/tox-dev/sphinx-a |
| `3.9.11` | 2026-03-24 | Medium | <!-- Release notes generated using configuration in .github/release.yaml at main -->  ## What's Changed * 🐛 fix(stubs): resolve imports inside if-blocks in .pyi stubs by @gaborbernat in https://github.com/tox-dev/sphinx-autodoc-typehints/pull/670 * 🐛 fix(stubs): evaluate stub-only definitions for annotation resolution by @gaborbernat in https://github.com/tox-dev/sphinx-autodoc-typehints/pull/671   **Full Changelog**: https://github.com/tox-dev/sphinx-autodoc-typehints/compare/3.9.10... |
| `3.9.10` | 2026-03-23 | Medium | <!-- Release notes generated using configuration in .github/release.yaml at main -->  ## What's Changed * 🐛 fix(stubs): use __new__ param annotations not class vars by @gaborbernat in https://github.com/tox-dev/sphinx-autodoc-typehints/pull/667 * 🐛 fix(stubs): prevent forward ref warnings from stub annotation pollution by @gaborbernat in https://github.com/tox-dev/sphinx-autodoc-typehints/pull/668   **Full Changelog**: https://github.com/tox-dev/sphinx-autodoc-typehints/compare/3.9.9... |
| `3.9.9` | 2026-03-20 | Low | <!-- Release notes generated using configuration in .github/release.yaml at main -->  ## What's Changed * 🐛 fix(stubs): resolve relative imports in .pyi stubs by @gaborbernat in https://github.com/tox-dev/sphinx-autodoc-typehints/pull/663   **Full Changelog**: https://github.com/tox-dev/sphinx-autodoc-typehints/compare/3.9.8...3.9.9 |
| `3.9.8` | 2026-03-09 | Low | <!-- Release notes generated using configuration in .github/release.yaml at main -->  ## What's Changed * 🐛 fix(docstring): preserve blank line after field list by @gaborbernat in https://github.com/tox-dev/sphinx-autodoc-typehints/pull/659   **Full Changelog**: https://github.com/tox-dev/sphinx-autodoc-typehints/compare/3.9.7...3.9.8 |
| `3.9.7` | 2026-03-05 | Low | <!-- Release notes generated using configuration in .github/release.yaml at main -->  ## What's Changed * 🐛 fix(resolver): resolve NamedTuple hints from class by @gaborbernat in https://github.com/tox-dev/sphinx-autodoc-typehints/pull/657   **Full Changelog**: https://github.com/tox-dev/sphinx-autodoc-typehints/compare/3.9.6...3.9.7 |

## Citation

- HTML: https://www.freshcrate.ai/projects/sphinx-autodoc-typehints
- Markdown: https://www.freshcrate.ai/projects/sphinx-autodoc-typehints.md
- Dependencies JSON: https://www.freshcrate.ai/api/projects/sphinx-autodoc-typehints/deps

_Generated by freshcrate.ai. Indexes pypi releases for AI-agent ecosystem packages._