Install & Compatibility
Where this runs
tested against v2.2.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.000s · 103.2MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 7.1s · import 0.000s · 103MB
105MB installed
● package 105MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
autodoc_pydantic (Sphinx Extension)
✓ # In conf.py, inside the project's source directory:
extensions = [
'sphinx.ext.autodoc',
'sphinx.ext.napoleon', # Or other docstring parsing extensions
'autodoc_pydantic'
]
✗ extensions = ['autodoc_pydantic.plugin']
autodoc-pydantic is enabled by adding its module name as a string to the `extensions` list in Sphinx's `conf.py`. There are no direct Python symbols usually imported by end-users.
To integrate autodoc-pydantic, first create a Sphinx project. Add 'sphinx.ext.autodoc' and 'autodoc_pydantic' to your `extensions` list in `conf.py`. Define your Pydantic models in Python modules. Then, use Sphinx's `automodule` combined with autodoc-pydantic's specific directives (e.g., `autodoc_pydantic_model`, `autodoc_pydantic_field`) in your documentation files to generate detailed API documentation for your Pydantic models.
# 1. Install dependencies: pip install autodoc-pydantic sphinx pydantic
# 2. Initialize a Sphinx project (e.g., using 'sphinx-quickstart')
# 3. Modify conf.py:
# Add 'sphinx.ext.autodoc' and 'autodoc_pydantic' to the extensions list.
# Example conf.py snippet:
# extensions = [
# 'sphinx.ext.autodoc',
# 'sphinx.ext.napoleon', # For Google/NumPy style docstrings
# 'autodoc_pydantic'
# ]
# 4. Create a Python file (e.g., 'my_models.py'):
# from pydantic import BaseModel, Field
#
# class User(BaseModel):
# """Represents a user in the system."""
# name: str = Field(..., description="The user's full name")
# age: int = Field(default=18, ge=0, description="The user's age")
# 5. Create an RST or Markdown file (e.g., 'models.rst'):
# .. automodule:: my_models
# :members:
#
# .. autodoc_pydantic_model:: my_models.User
# :model-show-json: False
# :model-show-config-summary: False
# 6. Build your documentation: make html (or sphinx-build -b html . _build)
Debug
Known issues
breakingVersion 2.0.0 introduced significant breaking changes in configuration options to align with Pydantic v2 and refine features. Many `autodoc_pydantic_*` settings were renamed, removed, or had their default behavior altered.fixConsult the official migration guide for autodoc-pydantic v2.0.0. For example, `autodoc_pydantic_model_show_config` was renamed to `autodoc_pydantic_model_show_json`, and `autodoc_pydantic_model_show_config_summary` was removed.
affects: >=2.0.0
gotchaFor autodoc-pydantic's directives to function correctly, `sphinx.ext.autodoc` must be present in your `extensions` list in `conf.py`. Without it, Pydantic model documentation will fail or appear incomplete.fixEnsure your `conf.py` includes `sphinx.ext.autodoc`, for instance: `extensions = ['sphinx.ext.autodoc', 'autodoc_pydantic']`.
affects: All
gotchaautodoc-pydantic automatically uses the `description` argument of Pydantic's `Field` as the field's docstring. This might lead to redundant or undesired output if you're also providing explicit docstrings or using other methods.fixIf you wish to control this behavior, set `autodoc_pydantic_field_show_description = False` in your `conf.py` or explore other `autodoc_pydantic_field_show_...` options to fine-tune how field descriptions are presented.
affects: All
gotchaWhen using Pydantic v1 vs. Pydantic v2, autodoc-pydantic adapts its behavior. If you switch Pydantic versions, especially upgrading from v1 to v2, your documentation output might change or require configuration adjustments.fixEnsure your autodoc-pydantic version is compatible with your installed Pydantic version (v2.0.0+ is recommended for Pydantic v2). Review your autodoc-pydantic configurations after a Pydantic version change, as some displays or features might have altered.
affects: All (during Pydantic version transitions)
Upgrade
Version history
2.2.0latest on PyPI · released Apr 27, 2024
Audit
Dependencies
sphinxrequiredCore documentation generation framework, autodoc-pydantic is a Sphinx extension.
pydanticrequiredLibrary for which this extension provides documentation support. Works with both Pydantic v1 and v2, but has different internal handling.