What causes "Multiple doctest failures" in pytest-dev/pytest?

Run pytest --doctest-modules on the specific file and read each listed failure to fix the expected output or the code.

pytest-dev/pytest · error · MultipleDoctestFailures

Multiple doctest failures

Error message

Multiple doctest failures

What it means

When pytest runs a doctest example and the doctest module records one or more DocTestFailure entries (example output mismatch or unexpected exception), pytest bundles them into a MultipleDoctestFailures exception. The message is a static 'Multiple doctest failures' summary; the individual failures are attached as the exception's .failures list and shown in the traceback.

Source

Thrown at src/_pytest/doctest.py:304

        self.funcargs: dict[str, object] = {}
        self._request = TopRequest(self, _ispytest=True)  # type: ignore[arg-type]

    def setup(self) -> None:
        self._request._fillfixtures()
        globs = dict(getfixture=self._request.getfixturevalue)
        for name, value in self._request.getfixturevalue("doctest_namespace").items():
            globs[name] = value
        self.dtest.globs.update(globs)

    def runtest(self) -> None:
        _check_all_skipped(self.dtest)
        self._disable_output_capturing_for_darwin()
        failures: list[doctest.DocTestFailure] = []
        # Type ignored because we change the type of `out` from what
        # doctest expects.
        self.runner.run(self.dtest, out=failures)  # type: ignore[arg-type]
        if failures:
            raise MultipleDoctestFailures(failures)

    def _disable_output_capturing_for_darwin(self) -> None:
        """Disable output capturing. Otherwise, stdout is lost to doctest (#985)."""
        if platform.system() != "Darwin":
            return
        capman = self.config.pluginmanager.getplugin("capturemanager")
        if capman:
            capman.suspend_global_capture(in_=True)
            out, err = capman.read_global_capture()
            sys.stdout.write(out)
            sys.stderr.write(err)

    # TODO: Type ignored -- breaks Liskov Substitution.
    def repr_failure(  # type: ignore[override]
        self,
        excinfo: ExceptionInfo[BaseException],
    ) -> str | TerminalRepr:
        import doctest

View on GitHub (pinned to 0d6fbdeffa)

Solutions

Run pytest --doctest-modules on the specific file and read each listed failure to fix the expected output or the code.
Re-generate the expected output by copying the actual output once you have confirmed it is correct.
If the example is order-sensitive, sort collections or use # doctest: +NORMALIZE_WHITESPACE / +ELLIPSIS directives as appropriate.

Example fix

// before
def add(a, b):
    """
    >>> add(1, 2)
    4
    """
    return a + b
// after
def add(a, b):
    """
    >>> add(1, 2)
    3
    """
    return a + b

Defensive patterns

Strategy: try-catch

Validate before calling

null

Type guard

null

Try / catch

from _pytest.doctest import MultipleDoctestFailures

try:
    run_doctest()
except MultipleDoctestFailures as e:
    for f in e.failures:
        print('example failed:', f.example, 'got:', f.got)
    raise

Prevention

Run --doctest-modules in CI to catch drift early.
Use +ELLIPSIS and +NORMALIZE_WHITESPACE for non-deterministic output.
Avoid examples whose output depends on dict ordering or float precision.

When it happens

Trigger: A docstring example whose expected output differs from actual; an example that raises an exception not matching the expected; whitespace/precision drift in floating point output.

Common situations: Updating a library so repr/output changed; non-deterministic output (dict ordering, floats); copy-pasted examples not kept in sync with code; platform-specific line endings.

Related errors

fixture '{argname}' not found

AI-assisted analysis of pytest-dev/pytest@0d6fbdeffa (2026-08-11). Data as JSON: /api/errors/bc1a5c4def28c2b2. Report an issue: GitHub.