---
id: pytest-doctestplus
version: "1.7.1"
license: BSD
license_treatment: permissive
maintenance: active
---

# pytest-doctestplus — Pytest plugin with advanced doctest features.

License: permissive · Maintenance: active · Downloads: 678.2K/mo

## What it is and what it does

pytest-doctestplus extends pytest's built-in doctest support to handle example code in Python docstrings and standalone documentation files (RST, Markdown, TeX). It solves the problem of testing documentation examples that may have floating-point precision variations, need to skip certain tests, or depend on remote data—situations where standard doctests fail or require workarounds.

The plugin integrates directly into pytest's collection and execution pipeline. You enable it via command-line flags (--doctest-plus, --doctest-rst, --doctest-ufunc) or configuration, then write doctests using standard Python doctest syntax plus optional directives like +FLOAT_CMP for approximate numeric comparison, +IGNORE_WARNINGS to suppress warnings, or +SHOW_WARNINGS to display them. It respects pytest's standard doctest options and can work alongside pytest-remotedata for tests that fetch external resources.

Use it for:

- Test code examples in Sphinx documentation to ensure they remain correct as the library evolves.
- Validate Markdown README files and tutorials contain working Python code snippets.
- Compare floating-point numerical results in doctests without brittle string matching on roundoff digits.
- Skip doctests in specific classes or functions during CI without removing the documentation examples.
- Test NumPy ufunc docstrings that contain example code requiring special handling.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

A pytest plugin that runs doctests in Python docstrings and documentation files (reStructuredText, Markdown, TeX) with advanced features like floating-point comparison and remote data handling.

Yes. This is a mature, actively maintained plugin (Production/Stable) with low install friction and no known vulnerabilities. Install it if you write documentation with code examples and want to ensure those examples stay correct. The floating-point comparison and remote-data features address real pain points in scientific and technical documentation testing.

## Install

pip install pytest-doctestplus
uv add pytest-doctestplus
poetry add pytest-doctestplus

## Installing pytest-doctestplus

Before you install: Low friction install with only pytest and packaging as runtime dependencies. Actively maintained with recent commits and stable releases; last update 200 days ago with ongoing development.

License in practice: BSD license (permissive) means you can use this freely in commercial and open-source projects with minimal restrictions.

Quickstart:

pip install pytest-doctestplus

# In your test file or docstring:
# >>> 1.0 / 3.0  # doctest: +FLOAT_CMP
# 0.333333333333333311

# Run with: pytest --doctest-plus --doctest-glob '*.md'

Requires Python 3.10 or later.

Verify before relying:

- Whether the plugin handles all edge cases in Markdown fenced code blocks consistently across different markdown parsers.
- Performance impact when running doctests on very large documentation sets or projects with thousands of examples.

## Package facts

- License: BSD (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 678.2K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

pytest doctest plugin, doctest rst markdown files, floating point doctest comparison, advanced doctest testing, documentation code examples testing, pytest docstring validation, doctest with remote data, doctest, documentation-testing, pytest-plugin

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